# X (Twitter) Audience & Spaces Intelligence | from $0.20/1K (`bovi/twitter-x-intelligence`) Actor Multi-mode X (Twitter) intelligence: (1) No-auth tweet hydration — batch by ID, zero proxy cost; (2) X Spaces metadata — host, title, listeners, playlist URL (PPE, only Spaces actor); (3) Follower/following delta KV feed — scheduled change alerts. Self-healing queryId. - **URL**: https://apify.com/bovi/twitter-x-intelligence.md - **Developed by:** [Vitalii Bondarev](https://apify.com/bovi) (community) - **Categories:** Social media, Marketing, Lead generation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.19 / 1,000 x-results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## X (Twitter) Audience & Spaces Intelligence **Multi-mode X intelligence actor with PPE pricing.** Three independent data modes in one actor — from zero-cost public tweet hydration to scheduled follower change tracking. --- ### Modes #### Mode `tweet_hydrate` — No-auth batch tweet hydration Fetch full tweet details for a list of tweet IDs using X's **public CDN embed endpoint** (`cdn.syndication.twimg.com`). No account, no proxy, no API key needed. This endpoint serves X's embed widgets to the entire web and runs on Fastly's CDN — it is public, high-availability, and does not validate any credential. **Fields returned:** `tweet_id`, `text`, `lang`, `created_at`, `favorite_count`, `conversation_count`, `author_screen_name`, `author_name`, `author_id`, `author_is_blue_verified`, `hashtags`, `mentions`, `tweet_url`. **Not available from this no-auth path:** retweet count, reply count, quote count, follower count. For those fields, use an authenticated mode. **Use cases:** bulk tweet content extraction, content moderation research, media monitoring pipelines, tweet archive hydration by ID list. --- #### Mode `spaces` — X Spaces metadata Fetch X Spaces metadata: host, title, current state (live/ended/scheduled), total live listeners, total replay watch count, playlist URL (`.m3u8`), scheduled/started/ended timestamps. **Why this mode exists:** As of mid-2026, there is exactly one competitor covering X Spaces on Apify — and it uses the **rental pricing model, which Apify is retiring on October 1, 2026**. All rental actors are force-migrated to PPE. This actor fills the **empty PPE Spaces lane** before the disruption window closes. **Auth requirement:** buyer-supplied `auth_token` + `ct0` cookies from an X account. The actor uses these only to call X's GraphQL API (AudioSpaceById operation) — your account credentials are never stored or logged beyond the single run. **Self-healing:** The GraphQL `queryId` (doc_id) for AudioSpaceById rotates every 2-4 weeks. This actor auto-resolves the current queryId from the live x.com JS bundle on each cold start — it does not break when X rotates their internal API IDs. **Use cases:** media / podcast teams tracking Space performance, brand monitoring, audience measurement, creator analytics. --- #### Mode `follower_delta` — KV-based follower change-feed Track who followed or unfollowed a set of X accounts over time. Each run: 1. Fetches the current follower (or following) list via GraphQL. 2. Compares it against the **KV-stored snapshot** from the previous run. 3. Pushes only the **delta events** — `new_follower`, `lost_follower`, `new_following`, `lost_following`. This is the "diff profile snapshots over time" approach that X's own category guides recommend — packaged as a turnkey scheduled actor. **Why delta matters:** X's Followers GraphQL has no `since` cursor. You must re-fetch the full list and diff it yourself. This actor handles that plumbing, so buyers only see what changed. **Scope:** Optimized for SMB/influencer accounts (≤500-2,000 followers per run). For mega-accounts with 100k+ followers, increase `maxUsers` with awareness of CU cost. **Use cases:** creator growth monitoring, competitor follower gain/loss tracking, brand monitoring, influencer vetting (is their follower base growing or churning?). --- ### Auth Requirement Summary | Mode | authToken | ct0 | Proxy needed | |---|---|---|---| | `tweet_hydrate` | No | No | No (optional fallback) | | `spaces` | Yes | Yes | Residential recommended | | `follower_delta` | Yes | Yes | Residential recommended | To get `authToken` and `ct0`: open x.com in Chrome → DevTools (F12) → Application → Cookies → x.com → copy `auth_token` and `ct0` values. --- ### Pricing **Pay Per Event (PPE):** $1.50 per 1,000 results. One charge per record pushed: - One tweet = one charge (Mode C) - One space = one charge (Mode A) - One delta event (new/lost follower) = one charge (Mode B) Compute cost is buyer-borne (runs on your Apify account). --- ### Technical Notes - **Signature:** x-client-transaction-id generated from the live ondemand JS per session. - **doc_id self-heal:** queryIds auto-resolved from x.com's main JS bundle on every cold run. - **Proxy:** Apify residential for authed modes (DC IPs are blocked by X at scale). tweet_hydrate uses DC with automatic residential fallback. - **No paid third-party proxy required.** Buyer pays Apify's standard residential CU rate. ### Integrations Built for social-listening analysts and media-monitoring teams hydrating tweet archives, tracking follower shifts, and X Spaces metadata — the JSON/dataset output drops into the tools you already run, no glue code: - **n8n / Make / Zapier** — trigger a run or pipe every new dataset item into 500+ apps (Google Sheets, Airtable, Slack, HubSpot, your database) with no code: [n8n](https://docs.apify.com/platform/integrations/n8n), [Make](https://docs.apify.com/platform/integrations/make), [Zapier](https://docs.apify.com/platform/integrations/zapier). - **Webhooks** — fire your own endpoint the moment a run finishes, to push results straight into your pipeline ([docs](https://docs.apify.com/platform/integrations/webhooks)). - **MCP server** — expose this actor as a tool to Claude, Cursor, or any [MCP client](https://mcp.apify.com) so an AI agent can pull this data mid-conversation ([guide](https://blog.apify.com/how-to-use-mcp/)). - **API & SDKs** — fetch the dataset as JSON, CSV, or Excel through the Apify REST API or the Python / JS SDKs. See all [Apify integrations](https://apify.com/integrations). # Actor input Schema ## `mode` (type: `string`): Which data to collect: • **tweet_hydrate** — No-auth batch tweet hydration. Supply tweetIds. Zero proxy cost, no account needed. Works immediately. • **spaces** — X Spaces metadata (host, title, state, total listeners, replay count, playlist URL). Requires authToken + ct0 cookies from your X account. • **follower_delta** — Follower or following change-feed. Each run fetches the full list, diffs it against the KV snapshot from the last run, and pushes only new/lost events. Ideal for scheduled monitoring. Requires authToken + ct0. ## `tweetIds` (type: `array`): List of numeric tweet IDs to hydrate. Example: ['1519480761749016577', '20']. Used only in tweet_hydrate mode. The actor fetches each tweet from X's public CDN embed endpoint — no proxy, no account required. Deleted, age-restricted, and NSFW tweets return no record (silently skipped). ## `spaceIds` (type: `array`): List of X Spaces IDs to fetch metadata for. The Space ID is the alphanumeric string at the end of a Spaces URL: x.com/i/spaces/. Example: ['1YqKDkVZwDkKV', '1dRKZlwEQzOGB']. Used only in spaces mode. Requires authToken + ct0. ## `targetHandles` (type: `array`): List of X screen names to monitor for follower/following changes. Include or omit the @ prefix — both work. Example: ['elonmusk', '@sama', 'OpenAI']. Used only in follower_delta mode. Requires authToken + ct0. Recommended: schedule this actor daily or weekly for ongoing monitoring. ## `direction` (type: `string`): Which relationship to track: 'followers' (who follows the target account) or 'following' (who the target account follows). Default: followers. ## `maxUsers` (type: `integer`): Maximum followers/following to fetch per target account per run. Higher values increase run cost (more GraphQL pages fetched) — keep at 500 or below for SMB/influencer accounts. For accounts with >10k followers, consider lowering to reduce CU cost. Default: 500. ## `emitFullList` (type: `boolean`): When true, the actor pushes the entire current follower/following list as records (mode=follower or mode=following) in addition to the delta events. Useful for an initial export on the first run. Significantly increases result count and PPE cost. Default: false (delta events only). ## `authToken` (type: `string`): Your X account's auth_token cookie value. Required for spaces and follower_delta modes. To find it: open X.com in Chrome → DevTools (F12) → Application → Cookies → x.com → copy the value of 'auth_token'. This is YOUR account's token — keep it confidential. The actor runs these modes on your account; suspension risk is account-holder's responsibility. ## `ct0` (type: `string`): Your X account's ct0 cookie value (the CSRF token, also called x-csrf-token). Required alongside authToken for authenticated modes. To find it: open X.com in Chrome → DevTools (F12) → Application → Cookies → x.com → copy the value of 'ct0'. ## `proxyConfiguration` (type: `object`): Proxy settings for the actor. For tweet_hydrate mode, proxies are optional (the CDN endpoint works from most IPs). For spaces and follower_delta modes, Apify residential proxies are strongly recommended — X blocks datacenter IPs at scale for authenticated GraphQL calls. Leave empty to use auto (Apify selects the best available proxy). ## Actor input object example ```json { "mode": "tweet_hydrate", "tweetIds": [ "1519480761749016577", "1812258574049157405", "1518623997054918657", "1585841080431321088", "1586104694421659648" ], "direction": "followers", "maxUsers": 500, "emitFullList": false, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } ```` # Actor output Schema ## `results` (type: `string`): Dataset containing Twitter X Intelligence records (mode, tweet\_id, author\_screen\_name, text, lang, created\_at, favorite\_count, conversation\_count, author\_is\_blue\_verified, tweet\_url, scraped\_at, space\_id, title, state, creator\_screen\_name, total\_live\_listeners, total\_replay\_watched, started\_at). # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "mode": "tweet_hydrate", "tweetIds": [ "1519480761749016577", "1812258574049157405", "1518623997054918657", "1585841080431321088", "1586104694421659648" ], "direction": "followers", "maxUsers": 500, "emitFullList": false, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }; // Run the Actor and wait for it to finish const run = await client.actor("bovi/twitter-x-intelligence").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "mode": "tweet_hydrate", "tweetIds": [ "1519480761749016577", "1812258574049157405", "1518623997054918657", "1585841080431321088", "1586104694421659648", ], "direction": "followers", "maxUsers": 500, "emitFullList": False, "proxyConfiguration": { "useApifyProxy": True, "apifyProxyGroups": ["RESIDENTIAL"], }, } # Run the Actor and wait for it to finish run = client.actor("bovi/twitter-x-intelligence").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "mode": "tweet_hydrate", "tweetIds": [ "1519480761749016577", "1812258574049157405", "1518623997054918657", "1585841080431321088", "1586104694421659648" ], "direction": "followers", "maxUsers": 500, "emitFullList": false, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }' | apify call bovi/twitter-x-intelligence --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=bovi/twitter-x-intelligence", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "X (Twitter) Audience & Spaces Intelligence | from $0.20/1K", "description": "Multi-mode X (Twitter) intelligence: (1) No-auth tweet hydration — batch by ID, zero proxy cost; (2) X Spaces metadata — host, title, listeners, playlist URL (PPE, only Spaces actor); (3) Follower/following delta KV feed — scheduled change alerts. Self-healing queryId.", "version": "0.1", "x-build-id": "Nm1KaSSVQKbTvoFGt" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/bovi~twitter-x-intelligence/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-bovi-twitter-x-intelligence", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/bovi~twitter-x-intelligence/runs": { "post": { "operationId": "runs-sync-bovi-twitter-x-intelligence", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/bovi~twitter-x-intelligence/run-sync": { "post": { "operationId": "run-sync-bovi-twitter-x-intelligence", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "tweet_hydrate", "spaces", "follower_delta" ], "type": "string", "description": "Which data to collect:\n\n• **tweet_hydrate** — No-auth batch tweet hydration. Supply tweetIds. Zero proxy cost, no account needed. Works immediately.\n\n• **spaces** — X Spaces metadata (host, title, state, total listeners, replay count, playlist URL). Requires authToken + ct0 cookies from your X account.\n\n• **follower_delta** — Follower or following change-feed. Each run fetches the full list, diffs it against the KV snapshot from the last run, and pushes only new/lost events. Ideal for scheduled monitoring. Requires authToken + ct0.", "default": "tweet_hydrate" }, "tweetIds": { "title": "Tweet IDs (for tweet_hydrate mode)", "type": "array", "description": "List of numeric tweet IDs to hydrate. Example: ['1519480761749016577', '20']. Used only in tweet_hydrate mode. The actor fetches each tweet from X's public CDN embed endpoint — no proxy, no account required. Deleted, age-restricted, and NSFW tweets return no record (silently skipped).", "items": { "type": "string" } }, "spaceIds": { "title": "Space IDs (for spaces mode)", "type": "array", "description": "List of X Spaces IDs to fetch metadata for. The Space ID is the alphanumeric string at the end of a Spaces URL: x.com/i/spaces/. Example: ['1YqKDkVZwDkKV', '1dRKZlwEQzOGB']. Used only in spaces mode. Requires authToken + ct0.", "items": { "type": "string" } }, "targetHandles": { "title": "Target X Handles (for follower_delta mode)", "type": "array", "description": "List of X screen names to monitor for follower/following changes. Include or omit the @ prefix — both work. Example: ['elonmusk', '@sama', 'OpenAI']. Used only in follower_delta mode. Requires authToken + ct0. Recommended: schedule this actor daily or weekly for ongoing monitoring.", "items": { "type": "string" } }, "direction": { "title": "Direction (for follower_delta mode)", "enum": [ "followers", "following" ], "type": "string", "description": "Which relationship to track: 'followers' (who follows the target account) or 'following' (who the target account follows). Default: followers.", "default": "followers" }, "maxUsers": { "title": "Max Users per Handle (for follower_delta mode)", "minimum": 10, "maximum": 10000, "type": "integer", "description": "Maximum followers/following to fetch per target account per run. Higher values increase run cost (more GraphQL pages fetched) — keep at 500 or below for SMB/influencer accounts. For accounts with >10k followers, consider lowering to reduce CU cost. Default: 500.", "default": 500 }, "emitFullList": { "title": "Also emit full follower list (for follower_delta mode)", "type": "boolean", "description": "When true, the actor pushes the entire current follower/following list as records (mode=follower or mode=following) in addition to the delta events. Useful for an initial export on the first run. Significantly increases result count and PPE cost. Default: false (delta events only).", "default": false }, "authToken": { "title": "X auth_token cookie (required for spaces + follower_delta)", "type": "string", "description": "Your X account's auth_token cookie value. Required for spaces and follower_delta modes. To find it: open X.com in Chrome → DevTools (F12) → Application → Cookies → x.com → copy the value of 'auth_token'. This is YOUR account's token — keep it confidential. The actor runs these modes on your account; suspension risk is account-holder's responsibility." }, "ct0": { "title": "X ct0 cookie / CSRF token (required for spaces + follower_delta)", "type": "string", "description": "Your X account's ct0 cookie value (the CSRF token, also called x-csrf-token). Required alongside authToken for authenticated modes. To find it: open X.com in Chrome → DevTools (F12) → Application → Cookies → x.com → copy the value of 'ct0'." }, "proxyConfiguration": { "title": "Proxy Configuration", "type": "object", "description": "Proxy settings for the actor. For tweet_hydrate mode, proxies are optional (the CDN endpoint works from most IPs). For spaces and follower_delta modes, Apify residential proxies are strongly recommended — X blocks datacenter IPs at scale for authenticated GraphQL calls. Leave empty to use auto (Apify selects the best available proxy)." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```