{ "openapi": "3.0.1", "info": { "title": "Twitter (X) Scraper — Tweets, Search, Timelines & Full Metrics", "description": "Scrape tweets by keyword, advanced query, hashtag, user timeline or tweet ID. Every tweet with views, bookmarks and the full author profile. No login, no API key.", "version": "0.0", "x-build-id": "dtN0hsnOXYU5JqUAF" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/brilliant_gum~twitter-x-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-brilliant_gum-twitter-x-scraper", "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/brilliant_gum~twitter-x-scraper/runs": { "post": { "operationId": "runs-sync-brilliant_gum-twitter-x-scraper", "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/brilliant_gum~twitter-x-scraper/run-sync": { "post": { "operationId": "run-sync-brilliant_gum-twitter-x-scraper", "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": { "searchTerms": { "title": "Search terms / advanced queries", "type": "array", "description": "One or more search queries. Each item accepts the full X advanced-search syntax (e.g. 'openai lang:en min_faves:100'). Runs without any login: operators are executed server-side by X, so results are real-time and carry every metric — views, bookmarks, likes, reposts, replies, quotes — plus the complete author profile. Supplying an authenticated session (authToken/csrfToken) is optional and only raises the ceiling on very large jobs.", "default": [], "items": { "type": "string" } }, "hashtags": { "title": "Hashtags", "type": "array", "description": "Hashtags to search (with or without '#'). Each becomes its own search query.", "default": [], "items": { "type": "string" } }, "rawQuery": { "title": "Raw advanced query", "type": "string", "description": "A single raw X advanced-search query, used verbatim (operators below are NOT auto-appended to it)." }, "tweetUrls": { "title": "Tweet URLs", "type": "array", "description": "Status URLs (https://x.com//status/). Looked up at full fidelity — real metrics and the complete author profile, no login needed.", "default": [], "items": { "type": "string" } }, "tweetIds": { "title": "Tweet IDs", "type": "array", "description": "Numeric tweet IDs to look up directly. Full fidelity: real metrics and the complete author profile, no login needed.", "default": [], "items": { "type": "string" } }, "fromUsers": { "title": "From users (timelines)", "type": "array", "description": "Handles (without @) whose recent tweets to pull via user-timeline (no login required).", "default": [], "items": { "type": "string" } }, "toUser": { "title": "Replies to user", "type": "string", "description": "Only tweets replying to this handle (compiled to 'to:'; search — needs auth)." }, "mentioning": { "title": "Mentioning users", "type": "array", "description": "Tweets mentioning these handles (compiled to '@handle'; search — needs auth).", "default": [], "items": { "type": "string" } }, "sinceDate": { "title": "Since date", "type": "string", "description": "Only tweets on/after this date, YYYY-MM-DD (→ since:)." }, "untilDate": { "title": "Until date", "type": "string", "description": "Only tweets before this date, YYYY-MM-DD (→ until:)." }, "sinceTime": { "title": "Since time (unix)", "type": "integer", "description": "Only tweets after this unix timestamp (seconds). More reliable than since: (→ since_time:)." }, "untilTime": { "title": "Until time (unix)", "type": "integer", "description": "Only tweets before this unix timestamp (seconds). More reliable than until: (→ until_time:)." }, "sinceId": { "title": "Since ID", "type": "string", "description": "Only tweets with ID greater than this (→ since_id:)." }, "maxId": { "title": "Max ID", "type": "string", "description": "Only tweets with ID at most this (→ max_id:)." }, "lang": { "title": "Language", "type": "string", "description": "BCP-47 language code, e.g. 'en' (→ lang:)." }, "minFaves": { "title": "Min likes", "type": "integer", "description": "Minimum like count (→ min_faves:)." }, "minRetweets": { "title": "Min retweets", "type": "integer", "description": "Minimum retweet count (→ min_retweets:)." }, "minReplies": { "title": "Min replies", "type": "integer", "description": "Minimum reply count (→ min_replies:)." }, "geocode": { "title": "Geocode", "type": "string", "description": "'lat,long,radius' e.g. '37.7764685,-122.4172004,10km' (→ geocode:)." }, "near": { "title": "Near place", "type": "string", "description": "Place name to search near (→ near:)." }, "withinRadius": { "title": "Within radius", "type": "string", "description": "Radius for 'near', e.g. '15mi' or '10km' (→ within:)." }, "placeId": { "title": "Place ID", "type": "string", "description": "X place ID (→ place:)." }, "filterMedia": { "title": "Only with media", "type": "boolean", "description": "filter:media", "default": false }, "filterImages": { "title": "Only with images", "type": "boolean", "description": "filter:images", "default": false }, "filterVideos": { "title": "Only with videos", "type": "boolean", "description": "filter:videos", "default": false }, "filterLinks": { "title": "Only with links", "type": "boolean", "description": "filter:links", "default": false }, "filterVerified": { "title": "Only verified", "type": "boolean", "description": "filter:verified", "default": false }, "filterBlue": { "title": "Only Blue verified", "type": "boolean", "description": "filter:blue_verified", "default": false }, "filterQuote": { "title": "Only quote tweets", "type": "boolean", "description": "filter:quote", "default": false }, "filterNativeRetweet": { "title": "Only native retweets", "type": "boolean", "description": "filter:nativeretweet", "default": false }, "includeReplies": { "title": "Include replies", "type": "boolean", "description": "If false → -filter:replies", "default": true }, "includeRetweets": { "title": "Include retweets", "type": "boolean", "description": "If false → -filter:nativeretweet", "default": true }, "includeQuotes": { "title": "Include quotes", "type": "boolean", "description": "If false → -filter:quote", "default": true }, "sort": { "title": "Sort / product", "enum": [ "Latest", "Top", "Photos", "Videos" ], "type": "string", "description": "Which results to return. \"Top\" gives established tweets with real engagement numbers. \"Latest\" returns tweets posted seconds ago — they are real, but their like/repost/bookmark counts are still zero because nobody has seen them yet.", "default": "Top" }, "maxTweetsPerTerm": { "title": "Max tweets per term", "minimum": 1, "type": "integer", "description": "Cap of tweets collected per query/term/timeline.", "default": 100 }, "maxTotalTweets": { "title": "Max total tweets", "minimum": 1, "type": "integer", "description": "Global cap across all jobs in this run.", "default": 1000 }, "outputPreset": { "title": "Output preset", "enum": [ "full", "compact", "csvFlat" ], "type": "string", "description": "Shape of each dataset record.", "default": "full" }, "jqFilter": { "title": "jq filter", "type": "string", "description": "Optional jq-style dot path (e.g. '.text') applied to each record for a lightweight projection. Leave empty for none." }, "monitorMode": { "title": "Monitor mode", "type": "boolean", "description": "Keyword-monitoring run (pairs with sinceLastRun).", "default": false }, "sinceLastRun": { "title": "Only since last run", "type": "boolean", "description": "With monitorMode: emit only tweets newer than the previous run (state kept in KV 'LAST_RUN').", "default": false }, "authToken": { "title": "X auth_token cookie", "type": "string", "description": "Optional. The 'auth_token' cookie from a logged-in x.com session. Raises the ceiling on very large search jobs. Standard use needs no credentials." }, "csrfToken": { "title": "X ct0 (csrf) cookie", "type": "string", "description": "Optional. The 'ct0' cookie from the same logged-in x.com session. Required together with authToken." }, "fxSearch": { "title": "Primary search path", "type": "boolean", "description": "Keep enabled. The real-time keyword search used for standard jobs.", "default": true }, "serpFallback": { "title": "Secondary search path", "type": "boolean", "description": "Keep enabled. Lets the Actor fall back to a slower search path when the primary one is rate-limited.", "default": true }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify proxy. Residential is strongly recommended for X.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "US" } }, "timelineFallback": { "title": "Timeline fallback", "type": "boolean", "description": "Keep enabled. Lets a user timeline fall back to a secondary source if the main one fails; those records are flagged with metricsDegraded.", "default": true } } }, "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 } } } } } } } } } }