x-twitter-scraper 0.12.3 → 0.13.0

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

@@ -1,4 +1,4 @@
-# Xquik Extraction Tools
+# Xquik extraction tools
 
 23 bulk data extraction tools. Each requires a specific target parameter.
 
@@ -14,20 +14,21 @@
 - [Exporting Results](#exporting-results)
 - [Estimating Usage](#estimating-usage)
 
-## Tool Types
+## Tool types
 
-### Tweet-Based (require `targetTweetId`)
+### Tweet-based (require `targetTweetId`)
 
-| Tool Type | Description |
-|-----------|-------------|
-| `reply_extractor` | Extract users who replied to a tweet |
-| `repost_extractor` | Extract users who retweeted a tweet |
-| `quote_extractor` | Extract users who quote-tweeted a tweet |
-| `thread_extractor` | Extract all tweets in a thread |
+| Tool Type           | Description                               |
+| ------------------- | ----------------------------------------- |
+| `reply_extractor`   | Extract users who replied to a tweet      |
+| `repost_extractor`  | Extract users who retweeted a tweet       |
+| `quote_extractor`   | Extract users who quote-tweeted a tweet   |
+| `thread_extractor`  | Extract all tweets in a thread            |
 | `article_extractor` | Extract article content linked in a tweet |
-| `favoriters` | Extract users who favorited a tweet |
+| `favoriters`        | Extract users who favorited a tweet       |
 
 **Example:**
+
 ```json
 {
   "toolType": "reply_extractor",
@@ -35,17 +36,18 @@
 }
 ```
 
-### User-Based (require `targetUsername`)
+### User-based (require `targetUsername`)
 
-| Tool Type | Description |
-|-----------|-------------|
-| `follower_explorer` | Extract followers of an account |
-| `following_explorer` | Extract accounts followed by a user |
+| Tool Type                    | Description                              |
+| ---------------------------- | ---------------------------------------- |
+| `follower_explorer`          | Extract followers of an account          |
+| `following_explorer`         | Extract accounts followed by a user      |
 | `verified_follower_explorer` | Extract verified followers of an account |
-| `mention_extractor` | Extract tweets mentioning an account |
-| `post_extractor` | Extract posts from an account |
+| `mention_extractor`          | Extract tweets mentioning an account     |
+| `post_extractor`             | Extract posts from an account            |
 
 **Example:**
+
 ```json
 {
   "toolType": "follower_explorer",
@@ -55,14 +57,15 @@
 
 The `@` prefix is automatically stripped if included.
 
-### User-Based by ID (require `targetUserId`)
+### User-based by ID (require `targetUserId`)
 
-| Tool Type | Description |
-|-----------|-------------|
-| `user_likes` | Extract tweets liked by a user |
+| Tool Type    | Description                      |
+| ------------ | -------------------------------- |
+| `user_likes` | Extract tweets liked by a user   |
 | `user_media` | Extract media tweets from a user |
 
 **Example:**
+
 ```json
 {
   "toolType": "user_likes",
@@ -70,16 +73,17 @@ The `@` prefix is automatically stripped if included.
 }
 ```
 
-### Community-Based (require `targetCommunityId`)
+### Community-based (require `targetCommunityId`)
 
-| Tool Type | Description |
-|-----------|-------------|
-| `community_extractor` | Extract members of a community |
-| `community_moderator_explorer` | Extract moderators of a community |
-| `community_post_extractor` | Extract posts from a community |
-| `community_search` | Search posts within a community (also requires `searchQuery`) |
+| Tool Type                      | Description                                                   |
+| ------------------------------ | ------------------------------------------------------------- |
+| `community_extractor`          | Extract members of a community                                |
+| `community_moderator_explorer` | Extract moderators of a community                             |
+| `community_post_extractor`     | Extract posts from a community                                |
+| `community_search`             | Search posts within a community (also requires `searchQuery`) |
 
 **Example:**
+
 ```json
 {
   "toolType": "community_extractor",
@@ -87,15 +91,16 @@ The `@` prefix is automatically stripped if included.
 }
 ```
 
-### List-Based (require `targetListId`)
+### List-based (require `targetListId`)
 
-| Tool Type | Description |
-|-----------|-------------|
-| `list_member_extractor` | Extract members of a list |
-| `list_post_extractor` | Extract posts from a list |
+| Tool Type                | Description                 |
+| ------------------------ | --------------------------- |
+| `list_member_extractor`  | Extract members of a list   |
+| `list_post_extractor`    | Extract posts from a list   |
 | `list_follower_explorer` | Extract followers of a list |
 
 **Example:**
+
 ```json
 {
   "toolType": "list_member_extractor",
@@ -103,13 +108,14 @@ The `@` prefix is automatically stripped if included.
 }
 ```
 
-### Space-Based (require `targetSpaceId`)
+### Space-based (require `targetSpaceId`)
 
-| Tool Type | Description |
-|-----------|-------------|
+| Tool Type        | Description                     |
+| ---------------- | ------------------------------- |
 | `space_explorer` | Extract participants of a Space |
 
 **Example:**
+
 ```json
 {
   "toolType": "space_explorer",
@@ -117,14 +123,15 @@ The `@` prefix is automatically stripped if included.
 }
 ```
 
-### Search-Based (require `searchQuery`)
+### Search-based (require `searchQuery`)
 
-| Tool Type | Description |
-|-----------|-------------|
-| `people_search` | Search for users by keyword |
+| Tool Type                | Description                                                         |
+| ------------------------ | ------------------------------------------------------------------- |
+| `people_search`          | Search for users by keyword                                         |
 | `tweet_search_extractor` | Search and extract tweets by keyword or hashtag (bulk, up to 1,000) |
 
 **Example (people search):**
+
 ```json
 {
   "toolType": "people_search",
@@ -133,6 +140,7 @@ The `@` prefix is automatically stripped if included.
 ```
 
 **Example (tweet search):**
+
 ```json
 {
   "toolType": "tweet_search_extractor",
@@ -141,30 +149,31 @@ The `@` prefix is automatically stripped if included.
 }
 ```
 
-### Tweet Search Filters
+### Tweet search filters
 
 The `tweet_search_extractor` tool type supports 16 additional filter fields that are converted to X search operators and combined with `searchQuery`:
 
-| 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 |
+| 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 |
 
 **Example with filters:**
+
 ```json
 {
   "toolType": "tweet_search_extractor",
@@ -192,7 +201,7 @@ The `tweet_search_extractor` tool type supports 16 additional filter fields that
 
 Statuses: `pending`, `running`, `completed`, `failed`.
 
-## Retrieving Results
+## Retrieve results
 
 ```
 GET /extractions/{id}
@@ -204,7 +213,7 @@ Returns paginated results (up to 1,000 per page). Each result includes:
 - `xFollowersCount`, `xVerified`, `xProfileImageUrl`
 - `tweetId`, `tweetText`, `tweetCreatedAt` (for tweet-based extractions)
 
-## Exporting Results
+## Export results
 
 ```
 GET /extractions/{id}/export?format=csv
@@ -214,7 +223,7 @@ Formats: `csv`, `json`, `md`, `md-document`, `pdf`, `txt`, `xlsx`. 100,000 row l
 
 Exports include enrichment columns not present in the API response.
 
-## Estimating Usage
+## Estimate usage
 
 ```
 POST /extractions/estimate

package/skills/x-twitter-scraper/references/mcp-setup.md

@@ -1,17 +1,17 @@
-# Xquik MCP Server Setup
+# Xquik MCP server setup
 
 Connect AI agents and IDEs to Xquik through Model Context Protocol. Add the
 remote URL and complete OAuth 2.1 in the browser. API-key fallback is
 client-specific. ChatGPT custom apps require OAuth and cannot present custom
 API keys.
 
-| Setting | Value |
-|---------|-------|
-| Protocol | Streamable HTTP |
-| Endpoint | `https://xquik.com/mcp` |
-| Authentication | OAuth 2.1 discovery; API key fallback |
-Let the client negotiate the current protocol. Use its returned discovery metadata.
-Never share privately cached catalogs across users or credentials.
+| Setting                                                                             | Value                                 |
+| ----------------------------------------------------------------------------------- | ------------------------------------- |
+| Protocol                                                                            | Streamable HTTP                       |
+| Endpoint                                                                            | `https://xquik.com/mcp`               |
+| Authentication                                                                      | OAuth 2.1 discovery; API key fallback |
+| Let the client negotiate the current protocol. Use its returned discovery metadata. |
+| Never share privately cached catalogs across users or credentials.                  |
 
 Xquik publishes these discovery documents:
 
@@ -103,7 +103,7 @@ async def run_xquik(api_key: str) -> str:
         return str(result.final_output)
 ```
 
-## Editors and Terminals
+## Editors & terminals
 
 ### Cursor
 
@@ -192,12 +192,12 @@ Or add it to `~/.gemini/settings.json` for user scope or
 
 ```json
 {
-      "mcpServers": {
-        "xquik": {
-          "type": "http",
-          "url": "https://xquik.com/mcp"
-        }
-      }
+  "mcpServers": {
+    "xquik": {
+      "type": "http",
+      "url": "https://xquik.com/mcp"
+    }
+  }
 }
 ```
 
@@ -218,24 +218,22 @@ save. This interactive path works across Copilot CLI command variants.
 In an interactive Copilot CLI session, run `/mcp auth xquik`. Enterprise policy
 may block servers that are not on the organization allowlist.
 
-## API-Key Fallback
+## API-key fallback
 
 Use this only when the client documents secure secret input.
 Client schemas differ. Never copy generic headers or store literal keys.
 
-## MCP Server Architecture
+## MCP server architecture
 
-Use live discovery to inspect the credential-scoped catalog and tools.
-Use REST for binary support downloads.
+Use live discovery to inspect the credential-scoped catalog and available mode.
+Code Mode exposes `docs`, `search`, and `execute`.
+Native mode derives operation tools from the same OpenAPI document.
 
-| Tool | Description | Usage |
-|------|-------------|------|
-| `explore` | Search the API endpoint catalog (read-only, no network calls) | Included |
-| `xquik` | Send confirmed Xquik API requests | Varies by endpoint |
+`docs` searches public guidance. `search` reads `spec.paths` without network
+access. `execute` calls `xquik.request()` inside a network-restricted sandbox.
+Authentication is injected. Tool code must never include credentials.
 
-`explore` searches the credential-scoped catalog. `xquik` executes authenticated
-operations with normalized snake_case responses. Authentication is injected, so
-tool code must never include credentials.
+Use REST for binary downloads.
 
 Keep credential, checkout & guest-wallet operations in REST or dashboard workflows:
 
@@ -244,22 +242,21 @@ Keep credential, checkout & guest-wallet operations in REST or dashboard workflo
 - Account top-up redirect
 - Guest wallet creation, status polling, and top-up
 
-Private reads, writes, monitors, webhooks, persistent resources, and metered bulk
-jobs require the user's explicit approval. Plan and credit changes stay
-dashboard-only.
+Private reads, writes, persistent resources, and metered bulk jobs require
+explicit approval. Plan and credit changes stay dashboard-only.
 
-## After Setup
+## After setup
 
-Use `explore` before unfamiliar operations. Use `xquik` only for the narrowest
-confirmed request.
+Use `docs` for guidance. Use `search` for unfamiliar operation contracts.
+Use `execute` only for the narrowest confirmed request.
 
-| Workflow | Steps |
-|----------|-------|
-| Search public posts | `explore` for the search route, then `xquik` with a bounded limit |
-| Set up alerts | Confirm target and ongoing usage, then create a monitor and webhook |
-| Run a giveaway | Confirm the source post, rules, and winner count, then create the draw |
-| Bulk extraction | Estimate, confirm the bound, create the job, then poll its status |
-| Publish a post | Confirm exact text and account, then execute the write |
+| Workflow            | Steps                                                                  |
+| ------------------- | ---------------------------------------------------------------------- |
+| Search public posts | Resolve the route with `search`, then run one bounded `execute` call   |
+| Set up alerts       | Confirm target and ongoing usage, then create a monitor and webhook    |
+| Run a giveaway      | Confirm the source post, rules, and winner count, then create the draw |
+| Bulk extraction     | Estimate, confirm the bound, create the job, then poll its status      |
+| Publish a post      | Confirm exact text and account, then execute the write                 |
 
 Handle failures from structured error fields: