{ "openapi": "3.0.1", "info": { "title": "X (Twitter) Scraper – Tweets, Profiles, Followers & Search API", "description": "Scrape X (Twitter) in real time — search tweets, profiles, timelines, followers, retweeters, quotes, lists, communities & Spaces. No API keys or login needed. Clean, LLM/MCP-ready JSON. Export to CSV, Excel, JSON or API. 15 tools in one Actor, pay only for what you use.", "version": "0.0", "x-build-id": "dLtlVpvsOXwAhA06E" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/b2b_leads~X-Real-Time-Data/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-b2b_leads-X-Real-Time-Data", "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/b2b_leads~X-Real-Time-Data/runs": { "post": { "operationId": "runs-sync-b2b_leads-X-Real-Time-Data", "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/b2b_leads~X-Real-Time-Data/run-sync": { "post": { "operationId": "run-sync-b2b_leads-X-Real-Time-Data", "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", "properties": { "enableSearch": { "title": "Search", "type": "boolean", "description": "Search X by keyword, hashtag, cashtag, or advanced query. Returns tweets (or people for People search type). Enabled by default.", "default": true }, "searchQueries": { "title": "Search queries", "type": "array", "description": "Full X search query strings (supports operators like min_faves:, lang:, -is:retweet). Use searchTerms for plain keywords.", "default": [], "items": { "type": "string" } }, "searchTerms": { "title": "Search keywords", "type": "array", "description": "Plain keywords auto-combined into OR queries. Required when Search is enabled unless searchQueries is set.", "default": [ "AI agents" ], "items": { "type": "string" } }, "searchType": { "title": "Search type", "enum": [ "Latest", "Top", "People", "Photos", "Videos" ], "type": "string", "description": "Result type returned by search.", "default": "Latest" }, "searchMaxResultsPerQuery": { "title": "Max results per query", "minimum": 0, "type": "integer", "description": "Maximum items to collect per search query. Set 0 for unlimited (bounded by maxItems).", "default": 100 }, "searchMaxPages": { "title": "Max pages per query", "minimum": 1, "type": "integer", "description": "Maximum cursor pages per query.", "default": 100 }, "searchLanguage": { "title": "Language filter", "type": "string", "description": "Optional ISO language code (e.g. en, es). Applied in query and re-validated post-fetch.", "default": "" }, "searchMinLikes": { "title": "Minimum likes", "minimum": 0, "type": "integer", "description": "Filter tweets with at least this many likes. 0 = no filter.", "default": 0 }, "searchExcludeRetweets": { "title": "Exclude retweets", "type": "boolean", "description": "Exclude retweets from search results.", "default": false }, "searchStartDate": { "title": "Start date (post-fetch filter)", "type": "string", "description": "ISO 8601 date — only include tweets on or after this date (filtered after fetch, not via since: operator).", "default": "" }, "searchEndDate": { "title": "End date (post-fetch filter)", "type": "string", "description": "ISO 8601 date — only include tweets on or before this date.", "default": "" }, "enableUserProfiles": { "title": "User Profiles", "type": "boolean", "description": "Fetch profile data for usernames or user IDs (batched up to 50 per request).", "default": false }, "profileUsernames": { "title": "Usernames", "type": "array", "description": "X usernames without @.", "default": [], "items": { "type": "string" } }, "profileUserIds": { "title": "User IDs", "type": "array", "description": "Numeric X user IDs.", "default": [], "items": { "type": "string" } }, "includeAboutAccount": { "title": "Include about-account metadata", "type": "boolean", "description": "Fetch extended account info (username history, affiliates, account source). One extra request per username.", "default": false }, "enableUserTweets": { "title": "User Tweets / Timeline", "type": "boolean", "description": "Fetch tweets posted by specific users.", "default": false }, "timelineUsernames": { "title": "Timeline usernames", "type": "array", "description": "Usernames whose timelines to scrape.", "default": [], "items": { "type": "string" } }, "timelineUserIds": { "title": "Timeline user IDs", "type": "array", "description": "User IDs whose timelines to scrape (skips username resolution).", "default": [], "items": { "type": "string" } }, "includeReplies": { "title": "Include replies", "type": "boolean", "description": "Include reply tweets in the timeline (tweets-and-replies vs tweets only).", "default": false }, "timelineMaxTweets": { "title": "Max tweets per user", "minimum": 0, "type": "integer", "description": "0 = unlimited (bounded by maxItems).", "default": 0 }, "timelineMaxPages": { "title": "Max pages per user", "minimum": 1, "type": "integer", "description": "Maximum cursor pages per user timeline.", "default": 100 }, "enableTweetDetails": { "title": "Tweet Details + Replies", "type": "boolean", "description": "Fetch full tweet data and optional conversation replies.", "default": false }, "tweetIds": { "title": "Tweet IDs", "type": "array", "description": "Numeric tweet IDs.", "default": [], "items": { "type": "string" } }, "tweetUrls": { "title": "Tweet URLs", "type": "array", "description": "Full X tweet URLs (IDs extracted automatically).", "default": [], "items": { "type": "string" } }, "includeConversationReplies": { "title": "Include conversation replies", "type": "boolean", "description": "Paginate replies for each tweet.", "default": false }, "repliesSort": { "title": "Replies sort", "enum": [ "Relevance", "Recency", "Likes" ], "type": "string", "description": "Order in which conversation replies are returned.", "default": "Relevance" }, "repliesMaxPerTweet": { "title": "Max replies per tweet", "minimum": 0, "type": "integer", "description": "0 = unlimited (bounded by maxItems).", "default": 0 }, "bulkMetricsOnly": { "title": "Bulk metrics only", "type": "boolean", "description": "Use batch details-by-ids for cheap engagement snapshots (no reply threads).", "default": false }, "enableEngagers": { "title": "Tweet Engagers", "type": "boolean", "description": "Fetch retweeters and/or quote tweets for given tweet IDs.", "default": false }, "engagerTweetIds": { "title": "Tweet IDs", "type": "array", "description": "Numeric tweet IDs to fetch engagers for.", "default": [], "items": { "type": "string" } }, "engagerTweetUrls": { "title": "Tweet URLs", "type": "array", "description": "Full X tweet URLs to fetch engagers for (IDs extracted automatically).", "default": [], "items": { "type": "string" } }, "engagerType": { "title": "Engager type", "enum": [ "retweeters", "quotes", "both" ], "type": "string", "description": "Which engagers to fetch: retweeters, quote tweets, or both.", "default": "both" }, "engagersMaxPerTweet": { "title": "Max engagers per tweet", "minimum": 0, "type": "integer", "description": "0 = unlimited (bounded by maxItems).", "default": 0 }, "engagersMaxPages": { "title": "Max pages per tweet", "minimum": 1, "type": "integer", "description": "Maximum cursor pages per tweet when fetching engagers.", "default": 100 }, "enableNetwork": { "title": "Followers & Following", "type": "boolean", "description": "Fetch followers, following, verified followers, or subscriptions for users.", "default": false }, "networkUsernames": { "title": "Usernames", "type": "array", "description": "Usernames whose network (followers/following) to scrape.", "default": [], "items": { "type": "string" } }, "networkUserIds": { "title": "User IDs", "type": "array", "description": "User IDs whose network to scrape (skips username resolution).", "default": [], "items": { "type": "string" } }, "networkType": { "title": "Network type", "enum": [ "followers", "following", "verified_followers", "subscriptions" ], "type": "string", "description": "Which relationship to fetch for each user.", "default": "followers" }, "networkMaxUsers": { "title": "Max users per source", "minimum": 0, "type": "integer", "description": "0 = unlimited (bounded by maxItems). Use for scraping all followers of an account.", "default": 0 }, "networkMaxPages": { "title": "Max pages per source", "minimum": 1, "type": "integer", "description": "Maximum cursor pages per user when fetching network data.", "default": 100 }, "networkPageSize": { "title": "Page size", "minimum": 1, "maximum": 100, "type": "integer", "description": "Items per page when the list endpoint supports count (max 100).", "default": 100 }, "networkMinFollowers": { "title": "Minimum followers filter", "minimum": 0, "type": "integer", "description": "Post-fetch filter: only include users with at least this many followers.", "default": 0 }, "enableFriendship": { "title": "Friendship Check", "type": "boolean", "description": "Check if one user follows another.", "default": false }, "friendshipPairs": { "title": "Friendship pairs", "type": "array", "description": "Array of {subject, target} usernames or IDs.", "default": [] }, "enableLists": { "title": "Lists", "type": "boolean", "description": "Scrape X list metadata, tweets, members, or followers.", "default": false }, "listIds": { "title": "List IDs", "type": "array", "description": "Numeric X list IDs.", "default": [], "items": { "type": "string" } }, "listUrls": { "title": "List URLs", "type": "array", "description": "Full X list URLs (IDs extracted automatically).", "default": [], "items": { "type": "string" } }, "listScrapeType": { "title": "List scrape types", "type": "array", "description": "What to fetch for each list.", "items": { "type": "string", "enum": [ "details", "tweets", "members", "followers" ] }, "default": [ "details", "tweets" ] }, "listMaxTweets": { "title": "Max tweets per list", "minimum": 0, "type": "integer", "description": "0 = unlimited (bounded by maxItems).", "default": 0 }, "listMaxMembers": { "title": "Max members per list", "minimum": 0, "type": "integer", "description": "0 = unlimited (bounded by maxItems). Also applies to list followers.", "default": 0 }, "listMaxPages": { "title": "Max pages per list", "minimum": 1, "type": "integer", "description": "Maximum cursor pages per list.", "default": 100 }, "enableCommunities": { "title": "Communities", "type": "boolean", "description": "Scrape community details, tweets, members, or search for communities.", "default": false }, "communityIds": { "title": "Community IDs", "type": "array", "description": "Numeric X community IDs.", "default": [], "items": { "type": "string" } }, "communityUrls": { "title": "Community URLs", "type": "array", "description": "Full X community URLs (IDs extracted automatically).", "default": [], "items": { "type": "string" } }, "communitySearchQueries": { "title": "Community search queries", "type": "array", "description": "Keywords to discover communities (requires 'search' in community scrape types).", "default": [], "items": { "type": "string" } }, "communityScrapeType": { "title": "Community scrape types", "type": "array", "description": "What to fetch for each community.", "items": { "type": "string", "enum": [ "details", "tweets", "members", "search" ] }, "default": [ "details", "tweets" ] }, "communitySortBy": { "title": "Community tweets sort", "enum": [ "Relevance", "Recency" ], "type": "string", "description": "Order in which community tweets are returned.", "default": "Recency" }, "communityMaxTweets": { "title": "Max tweets per community", "minimum": 0, "type": "integer", "description": "0 = unlimited (bounded by maxItems).", "default": 0 }, "communityMaxMembers": { "title": "Max members per community", "minimum": 0, "type": "integer", "description": "0 = unlimited (bounded by maxItems).", "default": 0 }, "communityMaxPages": { "title": "Max pages per community", "minimum": 1, "type": "integer", "description": "Maximum cursor pages per community.", "default": 100 }, "enableSpaces": { "title": "Spaces", "type": "boolean", "description": "Fetch X Space metadata and optional HLS stream URL.", "default": false }, "spaceIds": { "title": "Space IDs", "type": "array", "description": "X Space IDs.", "default": [], "items": { "type": "string" } }, "spaceUrls": { "title": "Space URLs", "type": "array", "description": "Full X Space URLs (IDs extracted automatically).", "default": [], "items": { "type": "string" } }, "includeStreamUrl": { "title": "Include stream URL", "type": "boolean", "description": "Resolve HLS audio stream URL from space mediaKey.", "default": false }, "enableTranslate": { "title": "Tweet Translation", "type": "boolean", "description": "Translate tweet text to a target language.", "default": false }, "translateTweetIds": { "title": "Tweet IDs to translate", "type": "array", "description": "Numeric tweet IDs to translate.", "default": [], "items": { "type": "string" } }, "translateTweetUrls": { "title": "Tweet URLs to translate", "type": "array", "description": "Full X tweet URLs to translate (IDs extracted automatically).", "default": [], "items": { "type": "string" } }, "translateTargetLang": { "title": "Target language", "type": "string", "description": "ISO language code (en, es, fr, de, ja, zh-CN, …).", "default": "en" }, "enableScrapeByUrl": { "title": "Scrape By URL", "type": "boolean", "description": "Paste any X URL — auto-detect page type and return structured data.", "default": false }, "scrapeUrls": { "title": "URLs", "type": "array", "description": "Any X URLs — tweets, profiles, lists, communities, Spaces, or search pages.", "default": [], "items": { "type": "string" } }, "scrapeExtractType": { "title": "Extract type", "enum": [ "auto", "tweet", "profile", "user_tweets", "list", "community", "space", "search" ], "type": "string", "description": "Force a specific extraction type, or auto-detect from each URL.", "default": "auto" }, "scrapeIncludeReplies": { "title": "Include replies (tweet URLs)", "type": "boolean", "description": "For tweet URLs, also paginate and return conversation replies.", "default": false }, "scrapeMaxItems": { "title": "Max items", "minimum": 0, "type": "integer", "description": "0 = unlimited per URL (bounded by maxItems).", "default": 0 }, "scrapeMaxPages": { "title": "Max pages", "minimum": 1, "type": "integer", "description": "Maximum cursor pages per URL.", "default": 100 }, "enableNotifications": { "title": "My Notifications", "type": "boolean", "description": "Read notifications for your own X account (requires authToken + sticky proxy).", "default": false }, "enableAnalytics": { "title": "My Analytics", "type": "boolean", "description": "Fetch engagement analytics for your own account.", "default": false }, "enableDmInbox": { "title": "My DM Inbox", "type": "boolean", "description": "Read DM conversations for your own account (requires authToken + ct0 + sticky proxy).", "default": false }, "authToken": { "title": "X auth token", "type": "string", "description": "Your X account login token (the 'auth_token' cookie). Required for any account-data feature (Notifications, Analytics, DM Inbox). HOW TO GET IT: 1) Log in to x.com in Chrome. 2) Press F12 → open the 'Application' tab → Cookies → https://x.com. 3) Copy the value of the cookie named 'auth_token'. Easier option: install the free 'Cookie-Editor' or 'EditThisCookie' Chrome extension, click it on x.com, and copy the 'auth_token' value. Treated as a secret and never logged." }, "ct0": { "title": "X ct0 token (CSRF cookie)", "type": "string", "description": "Your X 'ct0' cookie value. Required for DM Inbox (and encrypted X Chat). Get it the same way as the auth token: F12 → Application tab → Cookies → https://x.com → copy the 'ct0' value (or use the Cookie-Editor extension). Treated as a secret and never logged." }, "proxyHost": { "title": "Proxy host", "type": "string", "description": "Your proxy server address, e.g. proxy.example.com or 123.45.67.89. From your proxy provider's dashboard. Use a sticky (non-rotating) residential/ISP proxy — do NOT use Apify's rotating proxy for a logged-in account.", "default": "" }, "proxyPort": { "title": "Proxy port", "type": "string", "description": "Your proxy port number, e.g. 8080. From your proxy provider's dashboard.", "default": "" }, "proxyUsername": { "title": "Proxy username", "type": "string", "description": "The username/login for your proxy. From your proxy provider's dashboard." }, "proxyPassword": { "title": "Proxy password", "type": "string", "description": "The password for your proxy. From your proxy provider's dashboard. Treated as a secret and never logged." }, "userProxy": { "title": "Full proxy string (advanced — optional)", "type": "string", "description": "Advanced: instead of the four proxy fields above, paste a full sticky proxy string in host:port@user:pass format (e.g. proxy.example.com:8080@myuser:mypass). If set, this overrides the separate fields. Required (via this field or the four above) for account-data features." }, "notificationsType": { "title": "Notifications type", "enum": [ "All", "Verified", "Mentions" ], "type": "string", "description": "Which notifications timeline to read.", "default": "All" }, "notificationsMax": { "title": "Max notifications", "minimum": 0, "type": "integer", "description": "0 = unlimited (bounded by maxItems).", "default": 0 }, "notificationsMaxPages": { "title": "Max notification pages", "minimum": 1, "type": "integer", "description": "Maximum cursor pages when reading notifications.", "default": 100 }, "analyticsFromTime": { "title": "Analytics from", "type": "string", "description": "ISO 8601 start time. Empty = 30 days ago.", "default": "" }, "analyticsToTime": { "title": "Analytics to", "type": "string", "description": "ISO 8601 end time. Empty = now.", "default": "" }, "analyticsGranularity": { "title": "Analytics granularity", "enum": [ "Daily", "Weekly", "Monthly" ], "type": "string", "description": "Time bucket size for the analytics series.", "default": "Daily" }, "analyticsShowVerifiedFollowers": { "title": "Include verified follower metrics", "type": "boolean", "description": "Include verified follower counts in the analytics output.", "default": true }, "dmScope": { "title": "DM inbox scope", "enum": [ "trusted", "untrusted", "both" ], "type": "string", "description": "Which DM inbox timelines to read.", "default": "trusted" }, "dmIncludeEncrypted": { "title": "Include encrypted X Chat history", "type": "boolean", "description": "Also read encrypted X Chat history (requires xchatUserId and xchatPin).", "default": false }, "xchatUserId": { "title": "X Chat user ID", "type": "string", "description": "Your numeric user ID for encrypted DM setup." }, "xchatPin": { "title": "X Chat PIN", "type": "string", "description": "Your X Chat PIN (4–6 digits) if reading encrypted history." }, "dmConversationIds": { "title": "Conversation IDs", "type": "array", "description": "Specific conversation IDs. Empty = list inbox.", "default": [], "items": { "type": "string" } }, "dmMaxMessages": { "title": "Max messages per conversation", "minimum": 0, "type": "integer", "description": "0 = unlimited (bounded by maxItems).", "default": 0 }, "maxItems": { "title": "Max items (global)", "minimum": 1, "type": "integer", "description": "Global ceiling for this run. Default 100,000 — high enough to scrape all followers/replies/engagers. Lower to cap cost.", "default": 100000 }, "maxRetries": { "title": "Max retries", "minimum": 0, "type": "integer", "description": "Reactive retries on 429/5xx/transport errors before marking an item unavailable.", "default": 5 }, "retryBaseDelayMs": { "title": "Retry base delay (ms)", "minimum": 100, "type": "integer", "description": "Initial backoff delay before the first retry (grows exponentially).", "default": 2000 }, "retryMaxDelayMs": { "title": "Retry max delay (ms)", "minimum": 1000, "type": "integer", "description": "Maximum backoff delay between retries.", "default": 30000 }, "includeRaw": { "title": "Include raw upstream payload", "type": "boolean", "description": "Attach untouched upstream JSON under the raw field on each record.", "default": false }, "cacheTtlSeconds": { "title": "Cross-run cache TTL (seconds)", "minimum": 0, "type": "integer", "description": "Cache stable entities across runs in KV store. 0 = off (real-time).", "default": 0 } } }, "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 } } } } } } } } } }