x-twitter-scraper 0.5.2 → 0.6.0

package/skills/x-twitter-scraper/references/api-endpoints-drafts.md

@@ -0,0 +1,86 @@
+# Xquik REST API Endpoints: Drafts
+
+### Create Draft
+
+`POST /drafts`
+
+Save a tweet draft for later.
+
+**Request body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `text` | string | Yes | The draft tweet text |
+| `topic` | string | No | Topic the tweet is about |
+| `goal` | string | No | Optimization goal: `engagement`, `followers`, `authority`, `conversation` |
+
+**Response (201):**
+
+```json
+{
+  "id": "123",
+  "text": "draft text",
+  "topic": "product launch",
+  "goal": "engagement",
+  "createdAt": "2026-02-24T10:30:00.000Z",
+  "updatedAt": "2026-02-24T10:30:00.000Z"
+}
+```
+
+---
+
+### List Drafts
+
+`GET /drafts`
+
+List saved tweet drafts with cursor pagination.
+
+**Query parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `limit` | number | No | 50 | Results per page (max 50) |
+| `afterCursor` | string | No | - | Pagination cursor from previous response |
+
+**Response (200):**
+
+```json
+{
+  "drafts": [
+    {
+      "id": "123",
+      "text": "draft text",
+      "topic": "product launch",
+      "goal": "engagement",
+      "createdAt": "2026-02-24T10:30:00.000Z",
+      "updatedAt": "2026-02-24T10:30:00.000Z"
+    }
+  ],
+  "afterCursor": "cursor_string",
+  "hasMore": true
+}
+```
+
+---
+
+### Get Draft
+
+`GET /drafts/{id}`
+
+Get a specific draft by ID.
+
+**Response (200):** Single draft object.
+
+**Errors:** `400 invalid_id`, `404 draft_not_found`
+
+---
+
+### Delete Draft
+
+delete request to `/drafts/{id}`
+
+Delete a draft. Returns `204 No Content`.
+
+**Errors:** `400 invalid_id`, `404 draft_not_found`
+
+---

package/skills/x-twitter-scraper/references/api-endpoints-draws.md

@@ -0,0 +1,75 @@
+# Xquik REST API Endpoints: Draws
+
+### Create Draw
+
+```
+POST /draws
+```
+
+Run a giveaway draw from a tweet. Picks random winners from replies.
+
+**Body:**
+```json
+{
+  "tweetUrl": "https://x.com/user/status/1893456789012345678",
+  "winnerCount": 3,
+  "backupCount": 2,
+  "uniqueAuthorsOnly": true,
+  "mustRetweet": true,
+  "mustFollowUsername": "burakbayir",
+  "filterMinFollowers": 100,
+  "filterAccountAgeDays": 30,
+  "filterLanguage": "en",
+  "requiredKeywords": ["giveaway"],
+  "requiredHashtags": ["#contest"],
+  "requiredMentions": ["@xquik"]
+}
+```
+
+All filter fields are optional. Only `tweetUrl` is required.
+
+**Response:**
+```json
+{
+  "id": "42",
+  "tweetId": "1893456789012345678",
+  "tweetUrl": "https://x.com/user/status/1893456789012345678",
+  "tweetText": "Like & RT to enter! Picking 3 winners tomorrow.",
+  "tweetAuthorUsername": "xquik",
+  "tweetLikeCount": 4200,
+  "tweetRetweetCount": 1800,
+  "tweetReplyCount": 1500,
+  "tweetQuoteCount": 120,
+  "status": "completed",
+  "totalEntries": 1500,
+  "validEntries": 890,
+  "createdAt": "2026-02-24T10:00:00.000Z",
+  "drawnAt": "2026-02-24T10:01:00.000Z"
+}
+```
+
+### List Draws
+
+```
+GET /draws
+```
+
+Cursor-paginated. Returns compact draw objects.
+
+### Get Draw
+
+```
+GET /draws/{id}
+```
+
+Returns full draw details including winners.
+
+### Export Draw
+
+```
+GET /draws/{id}/export?format=csv&type=winners
+```
+
+Formats: `csv`, `json`, `md`, `md-document`, `pdf`, `txt`, `xlsx`. Types: `winners` (default), `entries`. Entry exports capped at 100,000 rows (PDF capped at 10,000).
+
+---

package/skills/x-twitter-scraper/references/api-endpoints-error-codes.md

@@ -0,0 +1,37 @@
+# Xquik REST API Endpoints: Error Codes
+
+| Status | Code | Meaning |
+|--------|------|---------|
+| 400 | `invalid_input` | Request body failed validation |
+| 400 | `invalid_id` | Path parameter is not a valid ID |
+| 400 | `invalid_json` | Invalid JSON in request body |
+| 400 | `invalid_tweet_url` | Tweet URL format is invalid |
+| 400 | `invalid_tweet_id` | Tweet ID is empty or invalid |
+| 400 | `invalid_username` | X username is empty or invalid |
+| 400 | `invalid_tool_type` | Extraction tool type not recognized |
+| 400 | `invalid_format` | Export format not `csv`, `json`, `md`, `md-document`, `pdf`, `txt`, or `xlsx` |
+| 400 | `invalid_params` | Export query parameters are missing or invalid |
+| 400 | `missing_query` | Required query parameter is missing |
+| 400 | `missing_params` | Required query parameters are missing |
+| 400 | `no_media` | Tweet has no downloadable media |
+| 400 | `webhook_inactive` | Webhook is disabled (test-webhook only) |
+| 401 | `unauthenticated` | Missing or invalid API key |
+| 403 | `account_needs_reauth` | X account session expired; use dashboard re-auth flow |
+| 402 | `no_subscription` | No active plan |
+| 402 | `subscription_inactive` | Plan is not active |
+| 402 | `no_credits` | No credit balance record exists |
+| 402 | `insufficient_credits` | Credit balance is too low |
+| 403 | `api_key_limit_reached` | API key limit reached (100 max) |
+| 404 | `not_found` | Resource does not exist |
+| 404 | `user_not_found` | X user not found |
+| 404 | `tweet_not_found` | Tweet not found |
+| 404 | `style_not_found` | No cached style found |
+| 404 | `draft_not_found` | Draft not found |
+| 409 | `monitor_already_exists` | Duplicate monitor for same username |
+| 422 | `login_failed` | Account connection failed; use dashboard re-auth flow |
+| 429 | - | Rate limited. Retry with backoff |
+| 429 | `x_api_rate_limited` | X data source rate limited. Retry |
+| 500 | `internal_error` | Server error |
+| 502 | `stream_registration_failed` | Stream registration failed. Retry |
+| 502 | `x_api_unavailable` | X data source temporarily unavailable |
+| 502 | `x_api_unauthorized` | X data source authentication failed. Retry |

package/skills/x-twitter-scraper/references/api-endpoints-events.md

@@ -0,0 +1,48 @@
+# Xquik REST API Endpoints: Events
+
+### List Events
+
+```
+GET /events
+```
+
+**Query parameters:**
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `monitorId` | string | Filter by monitor ID |
+| `eventType` | string | Filter by event type |
+| `limit` | number | Results per page (1-100, default 50) |
+| `after` | string | Cursor for next page |
+
+**Response:**
+```json
+{
+  "events": [
+    {
+      "id": "9010",
+      "type": "tweet.new",
+      "monitorId": "7",
+      "username": "elonmusk",
+      "occurredAt": "2026-02-24T16:45:00.000Z",
+      "data": {
+        "tweetId": "1893556789012345678",
+        "text": "Hello world",
+        "metrics": { "likes": 3200, "retweets": 890, "replies": 245 }
+      }
+    }
+  ],
+  "hasMore": true,
+  "nextCursor": "MjAyNi0wMi0yNFQxNjozMDowMC4wMDBa..."
+}
+```
+
+### Get Event
+
+```
+GET /events/{id}
+```
+
+Returns a single event with full details.
+
+---

package/skills/x-twitter-scraper/references/api-endpoints-extractions.md

@@ -0,0 +1,97 @@
+# Xquik REST API Endpoints: Extractions
+
+### Create Extraction
+
+```
+POST /extractions
+```
+
+Run a bulk data extraction job. See `references/extractions.md` for all 23 tool types.
+
+**Body:**
+```json
+{
+  "toolType": "reply_extractor",
+  "targetTweetId": "1893704267862470862",
+  "resultsLimit": 500
+}
+```
+
+`resultsLimit` (optional): Maximum results to extract. Stops early instead of fetching all data. Useful for controlling usage.
+
+**Tweet Search Filters** (`tweet_search_extractor` only):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `fromUser` | string | Author username |
+| `toUser` | string | Directed to user |
+| `mentioning` | string | Mentions user |
+| `language` | string | Language code (e.g., `en`) |
+| `sinceDate` | string | Start date (YYYY-MM-DD) |
+| `untilDate` | string | End date (YYYY-MM-DD) |
+| `mediaType` | string | `images`, `videos`, `gifs`, or `media` |
+| `minFaves` | number | Minimum likes |
+| `minRetweets` | number | Minimum retweets |
+| `minReplies` | number | Minimum replies |
+| `verifiedOnly` | boolean | Verified authors only |
+| `replies` | string | `include`, `exclude`, or `only` |
+| `retweets` | string | `include`, `exclude`, or `only` |
+| `exactPhrase` | string | Exact match text |
+| `excludeWords` | string | Comma-separated words to exclude |
+| `advancedQuery` | string | Raw X search operators appended to query |
+
+These filters are converted to X search operators and combined with `searchQuery`.
+
+**Response:**
+```json
+{
+  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "toolType": "reply_extractor",
+  "status": "running"
+}
+```
+
+### Estimate Extraction
+
+```
+POST /extractions/estimate
+```
+
+Preview usage before running. Same body as create.
+
+**Response:**
+```json
+{
+  "allowed": true,
+  "creditsAvailable": "50000",
+  "creditsRequired": "150",
+  "source": "replyCount",
+  "estimatedResults": 150
+}
+```
+
+### List Extractions
+
+```
+GET /extractions
+```
+
+Cursor-paginated. Filter by `status` and `toolType`.
+
+### Get Extraction
+
+```
+GET /extractions/{id}
+```
+
+Returns job details with paginated results (up to 1,000 per page).
+
+### Export Extraction
+
+```
+GET /extractions/{id}/export?format=csv
+```
+
+Formats: `csv`, `json`, `md`, `md-document`, `pdf`, `txt`, `xlsx`. 100,000 row limit (PDF 10,000). Exports include enrichment columns not in the API response.
+
+---

package/skills/x-twitter-scraper/references/api-endpoints-monitors.md

@@ -0,0 +1,74 @@
+# Xquik REST API Endpoints: Monitors
+
+### Create Monitor
+
+```
+POST /monitors
+```
+
+**Body:**
+```json
+{
+  "username": "elonmusk",
+  "eventTypes": ["tweet.new", "tweet.reply", "tweet.quote"]
+}
+```
+
+**Response:**
+```json
+{
+  "id": "7",
+  "username": "elonmusk",
+  "xUserId": "44196397",
+  "eventTypes": ["tweet.new", "tweet.reply", "tweet.quote"],
+  "createdAt": "2026-02-24T10:30:00.000Z"
+}
+```
+
+Event types: `tweet.new`, `tweet.quote`, `tweet.reply`, `tweet.retweet`, `webhook.test`.
+
+Returns `409 monitor_already_exists` if the username is already monitored.
+
+### List Monitors
+
+```
+GET /monitors
+```
+
+Returns all monitors (up to 200, no pagination). Response includes `monitors` array and `total` count.
+
+### Get Monitor
+
+```
+GET /monitors/{id}
+```
+
+### Update Monitor
+
+```
+PATCH /monitors/{id}
+```
+
+**Body:** `{ "eventTypes": [...], "isActive": true|false }` (both optional)
+
+### Delete Monitor
+
+```
+delete request to `/monitors/{id}`
+```
+
+Stops tracking and deletes all associated data.
+
+### Keyword Monitors
+
+```
+GET /monitors/keywords
+POST /monitors/keywords
+GET /monitors/keywords/{id}
+PATCH /monitors/keywords/{id}
+delete request to `/monitors/keywords/{id}`
+```
+
+Create and manage ongoing keyword monitors. Treat these as persistent resources: confirm the keyword query, event delivery plan, and ongoing usage before creating or enabling one.
+
+---

package/skills/x-twitter-scraper/references/api-endpoints-radar.md

@@ -0,0 +1,49 @@
+# Xquik REST API Endpoints: Radar
+
+### List Radar Items
+
+```
+GET /radar
+```
+
+Get trending topics and news from supported trend and news sources.
+
+**Query parameters:**
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `source` | string | Filter by public source: `google_trends`, `hacker_news`, `polymarket`, `wikipedia`, `github`, `reddit`. Omit to include all supported sources |
+| `category` | string | Filter by category: `general`, `tech`, `dev`, `science`, `culture`, `politics`, `business`, `entertainment` |
+| `limit` | number | Items per page (1-100, default 50) |
+| `hours` | number | Look-back window in hours (1-72, default 6) |
+| `region` | string | Region code: `US`, `GB`, `TR`, `ES`, `DE`, `FR`, `JP`, `IN`, `BR`, `CA`, `MX`, `global` (default) |
+
+**Response:**
+```json
+{
+  "items": [
+    {
+      "id": "12345",
+      "title": "Claude 4.6 Released",
+      "description": "Anthropic releases Claude 4.6...",
+      "url": "https://example.com/article",
+      "imageUrl": "https://example.com/image.png",
+      "source": "hacker_news",
+      "sourceId": "hn_12345",
+      "category": "tech",
+      "region": "global",
+      "language": "en",
+      "score": 450,
+      "metadata": { "points": 450, "numberComments": 132, "author": "pgdev" },
+      "publishedAt": "2026-03-05T10:00:00.000Z",
+      "createdAt": "2026-03-05T10:05:00.000Z"
+    }
+  ],
+  "hasMore": true,
+  "nextCursor": "NDUwfDIwMjYtMDMtMDRUMDg6MzA6MDAuMDAwWnwxMjM0NQ=="
+}
+```
+
+Fields: `id`, `title`, `description?`, `url?`, `imageUrl?`, `source`, `sourceId`, `category`, `region`, `language`, `score`, `metadata`, `publishedAt`, `createdAt`. Response includes `hasMore` and `nextCursor` for pagination.
+
+---

package/skills/x-twitter-scraper/references/api-endpoints-support.md

@@ -0,0 +1,47 @@
+# Xquik REST API Endpoints: Support
+
+### Create Ticket
+
+```
+POST /support/tickets
+```
+
+**Body:** `{ "subject": "...", "body": "..." }`
+
+**Response (201):** `{ id, subject, status, createdAt }`
+
+### List Tickets
+
+```
+GET /support/tickets
+```
+
+Returns all tickets for the authenticated user.
+
+### Get Ticket
+
+```
+GET /support/tickets/{id}
+```
+
+Returns ticket with messages.
+
+### Update Ticket
+
+```
+PATCH /support/tickets/{id}
+```
+
+Update ticket status.
+
+### Reply to Ticket
+
+```
+POST /support/tickets/{id}/messages
+```
+
+**Body:** `{ "body": "..." }`
+
+Add a message to an existing ticket.
+
+---

package/skills/x-twitter-scraper/references/api-endpoints-trends.md

@@ -0,0 +1,25 @@
+# Xquik REST API Endpoints: Trends
+
+### List Trends
+
+```
+GET /x/trends?woeid=1&count=30
+GET /trends?woeid=1&count=30
+```
+
+Metered. Plan access required. `/trends` is an alias of `/x/trends`. Cached, refreshes every 15 minutes.
+
+**WOEIDs:** 1 (Worldwide), 23424977 (US), 23424975 (UK), 23424969 (Turkey), 23424950 (Spain), 23424829 (Germany), 23424819 (France), 23424856 (Japan), 23424848 (India), 23424768 (Brazil), 23424775 (Canada), 23424900 (Mexico).
+
+**Response:**
+```json
+{
+  "trends": [
+    { "name": "#AI", "description": "...", "rank": 1, "query": "#AI" }
+  ],
+  "total": 30,
+  "woeid": 1
+}
+```
+
+---

package/skills/x-twitter-scraper/references/api-endpoints-tweet-style-cache.md

@@ -0,0 +1,155 @@
+# Xquik REST API Endpoints: Tweet Style Cache
+
+### Analyze & Cache Style
+
+`POST /styles`
+
+Fetch recent tweets from an X account and cache them for style analysis. **Consumes metered API usage.**
+
+**Request body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `username` | string | Yes | X username to analyze (without @) |
+
+**Response (201):**
+
+```json
+{
+  "xUsername": "elonmusk",
+  "tweetCount": 20,
+  "isOwnAccount": false,
+  "fetchedAt": "2026-02-24T10:30:00.000Z",
+  "tweets": [
+    {
+      "id": "1893456789012345678",
+      "text": "The future is now.",
+      "authorUsername": "elonmusk",
+      "createdAt": "2026-02-24T14:22:00.000Z"
+    }
+  ]
+}
+```
+
+---
+
+### List Cached Styles
+
+`GET /styles`
+
+List all cached tweet style profiles. Max 200 results, ordered by fetch date.
+
+**Response (200):**
+
+```json
+{
+  "styles": [
+    {
+      "xUsername": "elonmusk",
+      "tweetCount": 20,
+      "isOwnAccount": false,
+      "fetchedAt": "2026-02-24T10:30:00.000Z"
+    }
+  ]
+}
+```
+
+---
+
+### Save Custom Style
+
+`PUT /styles/{id}`
+
+Save a custom style profile from tweet texts. The body `label` controls the saved style label and replaces any existing style with that label.
+
+**Body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `label` | string | Yes | Style label name (1-30 characters) |
+| `tweets` | object[] | Yes | Array of tweet objects (1-100). Each must have a `text` field |
+
+**Response (200):** Style object with label, `tweetCount`, `isOwnAccount: false`, `fetchedAt`, and `tweets` array.
+
+**Errors:** `400 invalid_input`
+
+---
+
+### Get Cached Style
+
+`GET /styles/{id}`
+
+Get a cached style profile with full tweet data. `id` is the cached style label or username.
+
+**Response (200):** Full style object with `tweets` array.
+
+**Errors:** `404 style_not_found`
+
+---
+
+### Delete Cached Style
+
+delete request to `/styles/{id}`
+
+Delete a cached style by label or username. Returns `204 No Content`.
+
+**Errors:** `404 style_not_found`
+
+---
+
+### Compare Styles
+
+`GET /styles/compare?username1=A&username2=B`
+
+Compare two cached tweet style profiles side by side.
+
+**Query parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `username1` | string | Yes | First X username |
+| `username2` | string | Yes | Second X username |
+
+**Response (200):**
+
+```json
+{
+  "style1": { "xUsername": "user1", "tweetCount": 20, "isOwnAccount": true, "fetchedAt": "...", "tweets": [...] },
+  "style2": { "xUsername": "user2", "tweetCount": 15, "isOwnAccount": false, "fetchedAt": "...", "tweets": [...] }
+}
+```
+
+**Errors:** `400 missing_params`, `404 style_not_found`
+
+---
+
+### Analyze Performance
+
+`GET /styles/{id}/performance`
+
+Get live engagement metrics for cached tweets for a cached style label or username. **Consumes metered API usage.**
+
+**Response (200):**
+
+```json
+{
+  "xUsername": "elonmusk",
+  "tweetCount": 20,
+  "tweets": [
+    {
+      "id": "1893456789012345678",
+      "text": "The future is now.",
+      "likeCount": 42000,
+      "retweetCount": 8500,
+      "replyCount": 3200,
+      "quoteCount": 1100,
+      "viewCount": 5000000,
+      "bookmarkCount": 2400
+    }
+  ]
+}
+```
+
+**Errors:** `404 style_not_found`
+
+---