{ "openapi": "3.0.1", "info": { "title": "X (Twitter) Tweet Scraper", "description": "Scrape X (Twitter) tweets from searches, hashtags, profiles, lists, tweet URLs, and conversations. Get deduplicated posts, authors, engagement metrics, images, videos, quotes, retweets, and replies. Export results to JSON, CSV, Excel, XML, RSS, or access them through the API.", "version": "0.1", "x-build-id": "1z8UA7J5Z4RgyMBVn" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/smart_albatross~x-tweet-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-smart_albatross-x-tweet-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/smart_albatross~x-tweet-scraper/runs": { "post": { "operationId": "runs-sync-smart_albatross-x-tweet-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/smart_albatross~x-tweet-scraper/run-sync": { "post": { "operationId": "run-sync-smart_albatross-x-tweet-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 queries", "type": "array", "description": "Keywords, hashtags, or X advanced-search queries. Examples: artificial intelligence, #AI lang:en, or from:NASA filter:media. Each query shares the run-wide maxItems limit.", "items": { "type": "string" } }, "startUrls": { "title": "X or Twitter URLs", "type": "array", "description": "Profile, search, list, or exact tweet URLs from x.com or twitter.com. Exact tweet URLs return that tweet; profile and search URLs collect timeline results.", "items": { "type": "string" } }, "twitterHandles": { "title": "Profile handles", "type": "array", "description": "X/Twitter usernames whose tweets you want to collect. Both NASA and @NASA are accepted. Profile inputs can use extra timeline endpoints when Maximize unique results is enabled.", "items": { "type": "string" } }, "conversationIds": { "title": "Conversation or thread IDs", "type": "array", "description": "Numeric conversation IDs used to collect public tweets and replies from threads. The conversation ID is normally the ID in the original tweet URL.", "items": { "type": "string" } }, "maxItems": { "title": "Maximum tweets", "minimum": 1, "maximum": 100000, "type": "integer", "description": "Maximum number of unique tweets saved across the entire run, not per query or profile. Use a small value for your first run; exact tweet URLs may naturally return fewer items.", "default": 1000 }, "sort": { "title": "Search result order", "enum": [ "Latest", "Top", "Latest + Top" ], "type": "string", "description": "Latest prioritizes recent tweets. Top prioritizes popular/relevant tweets. Latest + Top runs both result streams and removes overlapping tweet IDs for broader coverage.", "default": "Latest" }, "maximizeResults": { "title": "Maximize unique results", "type": "boolean", "description": "For profile handles and profile URLs, combine search, tweet, media, and replies timelines, then deduplicate the union. This improves coverage but uses more requests.", "default": true }, "includeSearchTerms": { "title": "Include source query", "type": "boolean", "description": "Add searchTerm to every record so you can trace which search query or profile input first discovered the tweet.", "default": false }, "tweetLanguage": { "title": "Tweet language", "pattern": "^[A-Za-z]{2,3}$", "type": "string", "description": "Restrict search results to an ISO 639-1 language code. Choose a common language or type another two-letter code supported by X." }, "onlyVerifiedUsers": { "title": "Verified authors only", "type": "boolean", "description": "Return tweets only from verified accounts.", "default": false }, "onlyTwitterBlue": { "title": "X Premium authors only", "type": "boolean", "description": "Return tweets only from accounts with an X Premium blue check.", "default": false }, "onlyImage": { "title": "Tweets with images only", "type": "boolean", "description": "Return only tweets that contain at least one image.", "default": false }, "onlyVideo": { "title": "Tweets with videos only", "type": "boolean", "description": "Return only tweets that contain video media.", "default": false }, "onlyQuote": { "title": "Quote tweets only", "type": "boolean", "description": "Return only tweets that quote another tweet.", "default": false }, "author": { "title": "Posted by", "type": "string", "description": "Append a from: filter for this handle to every compatible source. Enter the username with or without @." }, "excludeAuthors": { "title": "Exclude authors", "type": "array", "description": "Exclude tweets authored by these handles. The Actor adds -from: operators and verifies every parsed record locally, case-insensitively, so X search leakage is removed.", "items": { "type": "string" } }, "inReplyTo": { "title": "Replies to", "type": "string", "description": "Append a to: filter and return tweets replying to this handle." }, "mentioning": { "title": "Mentioning", "type": "string", "description": "Return tweets that mention this handle. Enter the username with or without @." }, "minimumRetweets": { "title": "Minimum reposts", "minimum": 0, "type": "integer", "description": "Return tweets with at least this many reposts/retweets." }, "minimumFavorites": { "title": "Minimum likes", "minimum": 0, "type": "integer", "description": "Return tweets with at least this many likes." }, "minimumReplies": { "title": "Minimum replies", "minimum": 0, "type": "integer", "description": "Return tweets with at least this many replies." }, "start": { "title": "Posted on or after", "pattern": "^(\\d{4})-(0[1-9]|1[0-2])-([0-2]\\d|3[01])$", "type": "string", "description": "Include tweets posted on or after this date. Long ranges are divided into calendar windows and every result is checked locally against the exact UTC boundary." }, "end": { "title": "Posted before", "pattern": "^(\\d{4})-(0[1-9]|1[0-2])-([0-2]\\d|3[01])$", "type": "string", "description": "Include tweets posted before this date. The boundary is exclusive and is enforced locally even if X returns an out-of-range record." }, "geotaggedNear": { "title": "Near place", "type": "string", "description": "Return geotagged tweets near a place name, for example London or New York City." }, "withinRadius": { "title": "Radius from place", "pattern": "^\\d+(?:\\.\\d+)?(?:km|mi)$", "type": "string", "description": "Radius for Near place, such as 25km or 10mi." }, "geocode": { "title": "Geocode", "type": "string", "description": "X geocode expression in latitude,longitude,radius form, for example 37.7749,-122.4194,10km." }, "placeObjectId": { "title": "X place ID", "type": "string", "description": "Return tweets tagged with an exact X place object ID." } } }, "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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }