{ "openapi": "3.0.1", "info": { "title": "X Twitter Posts Search With Author Profile Details", "description": "X (Twitter) Posts Search โ€” Search X posts by keywords, hashtags, or advanced queries and extract post text, timestamps, engagement metrics, author profiles, bios, follower counts, locations, and profile URLs. Analyze conversations, audiences, trends, and competitor activity.", "version": "0.1", "x-build-id": "GwLaq8FQbnN0Hzxm5" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/scrapio~x-twitter-posts-search/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-scrapio-x-twitter-posts-search", "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/scrapio~x-twitter-posts-search/runs": { "post": { "operationId": "runs-sync-scrapio-x-twitter-posts-search", "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/scrapio~x-twitter-posts-search/run-sync": { "post": { "operationId": "run-sync-scrapio-x-twitter-posts-search", "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": [ "startUrls", "searchType" ], "properties": { "startUrls": { "title": "๐ŸŽฏ Targets to scrape โ€” profiles, @users, keywords, hashtags or search URLs", "type": "array", "description": "๐Ÿ“‹ **Add one row per target.** Mix and match freely!\n\nโœ… **What works:**\nโ€ข ๐Ÿ”— Profile URL โ€” `https://x.com/elonmusk`\nโ€ข ๐Ÿ‘ค Handle โ€” `@NASA` or `BarackObama`\nโ€ข ๐Ÿ”ค Keyword(s) โ€” `climate change` ยท `world cup final`\nโ€ข #๏ธโƒฃ Hashtag โ€” `#NASA` or `https://x.com/hashtag/NASA`\nโ€ข ๐Ÿ” X search URL โ€” `https://x.com/search?q=climate%20change&f=live` *(the base actor turned these into a non-existent profile called `@search` and returned nothing โ€” fixed here)*\nโ€ข ๐Ÿง  Search syntax โ€” `search: python from:NASA min_retweets:50`\n\n๐Ÿšซ **Skipped:** single-post links (`โ€ฆ/status/123โ€ฆ`).\n\n๐Ÿ’ก **Tip:** multi-word input = search ยท single word / profile URL = that account's timeline.\n๐Ÿ”‘ Keyword, hashtag and search-URL targets require the X session cookies below.", "items": { "type": "string" } }, "maxTweets": { "title": "๐Ÿ”ข Max posts per target", "minimum": 1, "maximum": 10000, "type": "integer", "description": "๐ŸŽฏ **Cap collection per target** (URL / user / keyword).\n\nโš–๏ธ Higher = more data + longer runs.\n๐Ÿ’ธ Tip: start small (50โ€“100) to validate, then scale up.\n๐Ÿ“Š X returns keyword results 20 per request and allows roughly **187 search requests per 15 minutes** per X account, so about **3,700 posts per window**.", "default": 10 }, "searchType": { "title": "๐Ÿ”Ž Search mode โ€” Top or Latest", "enum": [ "top", "latest" ], "type": "string", "description": "๐Ÿ† **Top** โ†’ popular & relevant posts (great for trends and analysis).\n๐Ÿ†• **Latest** โ†’ newest first (perfect with **Time window** for monitoring).\n\n๐Ÿง‘ On **profile** runs X itself has no sort parameter, so this reorders the posts that were fetched (newest-first for Latest, most-liked-first for Top) rather than changing which posts X returns.", "default": "top" }, "timeWindow": { "title": "๐Ÿ“… Time window โ€” last N days", "minimum": 1, "type": "integer", "description": "๐Ÿ—“๏ธ **Keep only posts newer than N days (UTC).**\n\nโœ… Applies on **both** search modes and on profile targets.\n๐Ÿ”• Leave empty to collect up to *Max posts* regardless of date." }, "timeWindowHours": { "title": "๐Ÿ• Time window โ€” last N hours", "minimum": 1, "type": "integer", "description": "โฐ **Keep only posts newer than N hours (UTC).**\n\nโœ… Applies on **both** search modes and on profile targets.\nโšก Use this for breaking-news / real-time monitoring.\n๐Ÿ‘‘ Takes precedence over days if both are set." }, "authToken": { "title": "๐Ÿ” auth_token cookie", "type": "string", "description": "๐Ÿช The value of the **`auth_token`** cookie on `x.com` (a ~40-character hex string).\n\n๐Ÿ”’ Stored encrypted, never logged.\nโš ๏ธ Rate limits are shared across every run using the same X account: about **187 search calls / 15 minutes**.\n๐Ÿ™ˆ Leave empty to run logged-out โ€” profile targets still work, keyword targets are reported as `login_required` and are **not** charged." }, "csrfToken": { "title": "๐Ÿ” ct0 cookie", "type": "string", "description": "๐Ÿช The value of the **`ct0`** cookie on `x.com` (a ~160-character hex string). Must come from the **same browser session** as the `auth_token` above.\n\n๐Ÿ”’ Stored encrypted, never logged." }, "enrichAuthorProfiles": { "title": "๐Ÿ”Ž Deep author lookup โ€” verification block", "type": "boolean", "description": "โž• Makes **one extra request per DISTINCT author** (not per post) to fetch fields that are not in the post payload:\n\nโ€ข `authorIsIdentityVerified`\nโ€ข `authorVerifiedSince`\nโ€ข `authorVerificationReason`\nโ€ข `authorAffiliatesCount`\nโ€ข `authorCreatorSubscriptions`\nโ€ข `authorBirthdate`\n\n๐Ÿ†“ This lookup runs **logged-out** โ€” your cookies are never used for it.\nโฑ๏ธ Costs about 0.4 s per distinct author. A profile run with 200 posts by one account costs exactly **one** lookup.\n๐Ÿ”• Off = every other author field is still returned.", "default": false }, "onlyVerifiedAuthors": { "title": "โœ… Only posts by verified authors", "type": "boolean", "description": "๐Ÿ”ต Keep only posts whose author has a **blue check** or an official **Government / Business** label.\n\n๐Ÿ†“ Evaluated from the post payload โ€” costs nothing and needs no deep lookup.\n๐Ÿ“‰ This is a strong filter: on a broad keyword search roughly **6 in 10** authors qualify.", "default": false }, "minAuthorFollowers": { "title": "๐Ÿ‘ฅ Minimum author followers", "minimum": 0, "type": "integer", "description": "๐Ÿ“Š Drop posts whose author has fewer than this many followers โ€” the quickest way to strip low-reach noise out of a keyword search.\n\n๐Ÿ†“ Evaluated from the post payload; costs nothing.\n๐Ÿ”• Leave empty to keep every author." }, "fullResolutionImages": { "title": "๐Ÿ–ผ๏ธ Full-resolution author avatar & banner", "type": "boolean", "description": "๐Ÿ“ธ Return the **400ร—400** avatar and the **1500ร—500** banner instead of X's 48ร—48 thumbnail (measured: ~26 KB vs ~2.5 KB).\n\n๐Ÿ”Ž The small thumbnail is always returned as well in `authorProfileImageUrlSmall`.", "default": true }, "proxyConfiguration": { "title": "๐ŸŒ Proxy โ€” recommended for stable runs", "type": "object", "description": "๐Ÿ”’ **Off** โ†’ direct connection.\nโœ… **On** โ†’ Apify Proxy (pick your groups in the UI).\n\nโญ X accepts datacenter and residential exits alike; **RESIDENTIAL** is still the safest default for long runs." } } }, "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 } } } } } } } } } }