# Twitter Keywords Scraper Pro (`crawlerbros/twitter-keywords-scraper-pro`) Actor Scrape tweets from Twitter/X by keywords with advanced filters: date range, language, engagement thresholds, media type, verified-only, and more. Returns full tweet data including author info, media, and engagement metrics. - **URL**: https://apify.com/crawlerbros/twitter-keywords-scraper-pro.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Social media, Developer tools, Lead generation - **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 21 bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing from $1.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. 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.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.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/platform/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 ## Twitter Keywords Scraper Pro Extract tweets from **Twitter / X** by keyword, hashtag, or full advanced search query. Built for researchers, marketers, and analysts who need reliable, structured Twitter data with deep filter support — date range, language, engagement thresholds, media type, verified-only, conversations, and more. Twitter session cookies are **required** for reliable extraction. See the **Authentication** section below. ### What you get For each tweet the scraper returns: | Field | Description | | --- | --- | | `id` | Tweet ID | | `url` / `twitterUrl` | Direct tweet URL | | `text` | Full tweet text (with hashtags and mentions intact) | | `createdAt` | ISO 8601 timestamp the tweet was posted | | `isReply` | `true` if the tweet is a reply | | `isRetweet` | `true` if the tweet is a retweet | | `isQuote` | `true` if the tweet quotes another tweet | | `quoteId` | ID of the quoted tweet (when `isQuote=true`) | | `replyCount` | Reply count | | `retweetCount` | Retweet count | | `likeCount` | Like count | | `quoteCount` | Quote count | | `bookmarkCount` | Bookmark count | | `viewCount` | View count | | `engagementScore` | Composite engagement metric (replies + retweets + likes) | | `hashtags` | Array of hashtags used (without `#`) | | `mentions` | Array of mentioned users (without `@`) | | `urls` | External URLs in the tweet | | `media` | Array of media objects — `{ type: image|video|gif, url }` | | `author` | Author profile snippet — `userName`, `name`, `profilePicture`, `isBlueVerified` | | `keyword` | The search keyword that found this tweet | | `scrapedAt` | ISO 8601 UTC timestamp of extraction | Empty fields are dropped so the dataset stays clean. ### Input | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `keywords` | Array | **required** | Keywords, phrases, or hashtags to search. Each keyword runs as a separate search. | | `maxItems` | Integer | `20` | Max tweets per keyword (1-1000). | | `sort` | Enum | `Top` | `Top`, `Latest`, or `Top + Latest` (dual-pass dedup). | | `tweetLanguage` | String | — | ISO 639-1 language code (`en`, `es`, `de`, `ja`, …). | | `startDate` | String | — | Earliest date `YYYY-MM-DD`. | | `endDate` | String | — | Latest date `YYYY-MM-DD`. | | `minimumRetweets` | Integer | — | Filter for tweets with at least N retweets. | | `minimumLikes` | Integer | — | Filter for tweets with at least N likes. | | `minimumReplies` | Integer | — | Filter for tweets with at least N replies. | | `onlyImages` | Boolean | `false` | Only tweets containing images. | | `onlyVideos` | Boolean | `false` | Only tweets containing videos. | | `onlyQuotes` | Boolean | `false` | Only quote tweets. | | `onlyVerifiedUsers` | Boolean | `false` | Only tweets from verified (Blue) accounts. | | `mentioning` | String | — | Tweets mentioning this handle. | | `author` | String | — | Tweets posted FROM this handle. | | `inReplyTo` | String | — | Tweets that are replies TO this handle. | | `conversationId` | String | — | Tweets in a specific conversation thread (root tweet ID). | | `cookies` | String | **required** | Twitter/X session cookies (JSON array). See Authentication. | | `proxyConfiguration` | Object | — | Optional proxy. Leave off unless you hit IP-based blocks. | #### Example input — minimal ```json { "keywords": ["artificial intelligence"], "maxItems": 50, "cookies": "[{\"name\":\"auth_token\",\"value\":\"YOUR_TOKEN\",\"domain\":\".x.com\"}]" } ```` #### Example input — advanced filters ```json { "keywords": ["#TechNews", "machine learning"], "maxItems": 200, "sort": "Top + Latest", "tweetLanguage": "en", "startDate": "2026-04-01", "endDate": "2026-04-30", "minimumLikes": 100, "onlyVerifiedUsers": true, "cookies": "[...]" } ``` #### Example input — conversation thread ```json { "keywords": [""], "conversationId": "1881234567890123456", "maxItems": 500, "cookies": "[...]" } ``` ### Example output ```json { "id": "1881234567890123456", "url": "https://x.com/openai/status/1881234567890123456", "twitterUrl": "https://x.com/openai/status/1881234567890123456", "text": "Introducing GPT-4 Turbo. More capable, cheaper, and updated knowledge. #AI", "createdAt": "2026-04-15T14:32:00.000Z", "isReply": false, "isRetweet": false, "isQuote": false, "replyCount": 1240, "retweetCount": 8500, "likeCount": 42000, "quoteCount": 320, "bookmarkCount": 3100, "viewCount": 9800000, "engagementScore": 51740, "hashtags": ["AI"], "mentions": [], "urls": ["https://openai.com/gpt4turbo"], "media": [ { "type": "image", "url": "https://pbs.twimg.com/media/AbCdEf.jpg" } ], "author": { "userName": "OpenAI", "name": "OpenAI", "profilePicture": "https://pbs.twimg.com/profile_images/.../photo_400x400.jpg", "isBlueVerified": true }, "keyword": "machine learning", "scrapedAt": "2026-05-05T13:42:18Z" } ``` ### Authentication Twitter/X requires a logged-in session for reliable search results. The `cookies` input is a JSON array of your browser cookies for `x.com`. #### How to export your cookies 1. Log into [x.com](https://x.com) in Chrome or Firefox. 2. Install the [Cookie-Editor](https://cookie-editor.com) extension. 3. Click the extension icon → **Export → Export as JSON**. 4. Paste the JSON array into the `cookies` input field. The two cookies that absolutely must be present are `auth_token` and `ct0`. Cookies typically last 30-60 days before they need refreshing. #### Cookie format ```json [ { "name": "auth_token", "value": "YOUR_AUTH_TOKEN", "domain": ".x.com", "path": "/", "httpOnly": true, "secure": true }, { "name": "ct0", "value": "YOUR_CT0_VALUE", "domain": ".x.com", "path": "/", "httpOnly": false, "secure": true } ] ``` > Keep your cookies private — they grant access to your X account. ### Use cases - **Brand monitoring** — Track real-time mentions of your brand or product. - **Competitive research** — Monitor competitor keywords, hashtags, and sentiment. - **Trend analysis** — Capture viral content using engagement thresholds. - **Academic research** — Collect tweets by date range, language, and topic. - **Hashtag campaign tracking** — Measure reach for branded campaign hashtags. - **Conversation analysis** — Pull every tweet in a thread with `conversationId`. - **Influencer discovery** — Combine `minimumLikes` + `onlyVerifiedUsers` to surface high-impact accounts. ### FAQ **Why are cookies required?** Twitter/X locks search results behind a login wall. Without valid cookies, search returns either nothing or a curated old-tweets feed. Cookies authenticate the actor as a real session so you get fresh, relevant results. **My results look stale or limited — what's wrong?** Either your cookies have expired or you're hitting a rate limit. Re-export fresh cookies (Chrome → Cookie-Editor → Export). If results stay limited, lower `maxItems` and let the actor run multiple smaller passes. **Can I combine filters?** Yes — every filter is AND-combined. A query like `keywords=["AI"], minimumLikes=100, onlyVerifiedUsers=true, tweetLanguage="en"` returns English tweets about AI from verified accounts with at least 100 likes. **How does `Top + Latest` work?** It runs two search passes (most relevant first, then chronological) and deduplicates by tweet ID. You get broader coverage than either mode alone, with no duplicate rows. **What's the maximum I can scrape per keyword?** Up to 1000 tweets per keyword per run, capped by Twitter's search index depth. For very high-volume queries, narrow with date range or engagement filters and run multiple passes. **Will my account get banned?** The actor uses random delays, scrolls naturally, and mimics human browsing. Risk is low for typical usage, but avoid hammering the same query for hundreds of thousands of tweets back-to-back. Use a dedicated account, not your primary one, if you're running heavy workloads. **What if every search returns zero tweets?** The actor emits a single sentinel record with `type: "twitter_keywords_blocked"` and a clear `reason` (e.g. `expired_cookies`) so the run exits cleanly with a non-empty dataset and you immediately know what to fix. **How current is the data?** Live — every run queries Twitter/X at request time. Schedule the actor for hourly or daily refreshes. ### Limitations - Twitter/X search index depth varies — very old tweets may not be retrievable even with date filters. - Protected (private) accounts are excluded unless you authenticate with cookies from a follower. - Cookies expire — refresh every ~30-60 days for steady performance. - Engagement counts for very old tweets may differ slightly from the official API. # Actor input Schema ## `keywords` (type: `array`): One or more keywords or phrases to search on Twitter/X. Supports advanced search syntax (e.g. '#AI' or 'python site:github.com'). ## `maxItems` (type: `integer`): Maximum number of tweets to collect per keyword. ## `sort` (type: `string`): Result ordering. 'Top + Latest' runs two passes and combines results. ## `startDate` (type: `string`): Only return tweets on or after this date. Format: YYYY-MM-DD ## `endDate` (type: `string`): Only return tweets on or before this date. Format: YYYY-MM-DD ## `minimumRetweets` (type: `integer`): Only return tweets with at least this many retweets. ## `minimumLikes` (type: `integer`): Only return tweets with at least this many likes. ## `minimumReplies` (type: `integer`): Only return tweets with at least this many replies. ## `onlyImages` (type: `boolean`): Return only tweets that contain images. ## `onlyVideos` (type: `boolean`): Return only tweets that contain videos. ## `onlyQuotes` (type: `boolean`): Return only quote tweets. ## `onlyVerifiedUsers` (type: `boolean`): Return only tweets from verified accounts. ## `mentioning` (type: `string`): Only return tweets that mention this Twitter handle (with or without @). ## `tweetLanguage` (type: `string`): Filter to tweets in this language. ISO 639-1 code (en, es, fr, de, ja, etc.). Leave empty for all languages. ## `author` (type: `string`): Only return tweets posted BY this Twitter handle (with or without @). E.g. anthropic ## `inReplyTo` (type: `string`): Only return tweets that are replies to this Twitter handle (with or without @). ## `conversationId` (type: `string`): Only return tweets in this conversation thread (the root tweet ID). ## `cookies` (type: `string`): **Required.** Your Twitter/X session cookies in JSON format (array of cookie dicts). Twitter heavily restricts unauthenticated browsing — a valid session is mandatory. Extract via browser devtools → Application → Cookies on x.com (must include auth\_token, ct0). Without cookies, the run returns a single placeholder record indicating cookies are needed. ## `proxyConfiguration` (type: `object`): Optional proxy to route browser traffic through. Disabled by default (adds cost). Enable if you encounter IP-based rate limiting or blocks. ## Actor input object example ```json { "keywords": [ "apify" ], "maxItems": 20, "sort": "Top", "onlyImages": false, "onlyVideos": false, "onlyQuotes": false, "onlyVerifiedUsers": false } ``` # 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 = { "keywords": [ "apify" ], "cookies": "" }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/twitter-keywords-scraper-pro").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 = { "keywords": ["apify"], "cookies": "", } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/twitter-keywords-scraper-pro").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 '{ "keywords": [ "apify" ], "cookies": "" }' | apify call crawlerbros/twitter-keywords-scraper-pro --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/twitter-keywords-scraper-pro", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Twitter Keywords Scraper Pro", "description": "Scrape tweets from Twitter/X by keywords with advanced filters: date range, language, engagement thresholds, media type, verified-only, and more. Returns full tweet data including author info, media, and engagement metrics.", "version": "1.6", "x-build-id": "16EV1fxaVjtdusH8P" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~twitter-keywords-scraper-pro/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-twitter-keywords-scraper-pro", "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/crawlerbros~twitter-keywords-scraper-pro/runs": { "post": { "operationId": "runs-sync-crawlerbros-twitter-keywords-scraper-pro", "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/crawlerbros~twitter-keywords-scraper-pro/run-sync": { "post": { "operationId": "run-sync-crawlerbros-twitter-keywords-scraper-pro", "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": [ "keywords", "cookies" ], "properties": { "keywords": { "title": "Search Keywords", "minItems": 1, "type": "array", "description": "One or more keywords or phrases to search on Twitter/X. Supports advanced search syntax (e.g. '#AI' or 'python site:github.com').", "items": { "type": "string" } }, "maxItems": { "title": "Max Tweets Per Keyword", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Maximum number of tweets to collect per keyword.", "default": 20 }, "sort": { "title": "Sort Order", "enum": [ "Top", "Latest", "Top + Latest" ], "type": "string", "description": "Result ordering. 'Top + Latest' runs two passes and combines results.", "default": "Top" }, "startDate": { "title": "Start Date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Only return tweets on or after this date. Format: YYYY-MM-DD" }, "endDate": { "title": "End Date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Only return tweets on or before this date. Format: YYYY-MM-DD" }, "minimumRetweets": { "title": "Minimum Retweets", "minimum": 0, "type": "integer", "description": "Only return tweets with at least this many retweets." }, "minimumLikes": { "title": "Minimum Likes", "minimum": 0, "type": "integer", "description": "Only return tweets with at least this many likes." }, "minimumReplies": { "title": "Minimum Replies", "minimum": 0, "type": "integer", "description": "Only return tweets with at least this many replies." }, "onlyImages": { "title": "Images Only", "type": "boolean", "description": "Return only tweets that contain images.", "default": false }, "onlyVideos": { "title": "Videos Only", "type": "boolean", "description": "Return only tweets that contain videos.", "default": false }, "onlyQuotes": { "title": "Quote Tweets Only", "type": "boolean", "description": "Return only quote tweets.", "default": false }, "onlyVerifiedUsers": { "title": "Verified Users Only", "type": "boolean", "description": "Return only tweets from verified accounts.", "default": false }, "mentioning": { "title": "Mentioning Handle", "type": "string", "description": "Only return tweets that mention this Twitter handle (with or without @)." }, "tweetLanguage": { "title": "Tweet Language", "type": "string", "description": "Filter to tweets in this language. ISO 639-1 code (en, es, fr, de, ja, etc.). Leave empty for all languages." }, "author": { "title": "From Author", "type": "string", "description": "Only return tweets posted BY this Twitter handle (with or without @). E.g. anthropic" }, "inReplyTo": { "title": "In Reply To", "type": "string", "description": "Only return tweets that are replies to this Twitter handle (with or without @)." }, "conversationId": { "title": "Conversation ID", "type": "string", "description": "Only return tweets in this conversation thread (the root tweet ID)." }, "cookies": { "title": "Twitter Cookies (Required)", "type": "string", "description": "**Required.** Your Twitter/X session cookies in JSON format (array of cookie dicts). Twitter heavily restricts unauthenticated browsing — a valid session is mandatory. Extract via browser devtools → Application → Cookies on x.com (must include auth_token, ct0). Without cookies, the run returns a single placeholder record indicating cookies are needed." }, "proxyConfiguration": { "title": "Proxy Configuration", "type": "object", "description": "Optional proxy to route browser traffic through. Disabled by default (adds cost). Enable if you encounter IP-based rate limiting or blocks." } } }, "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 } } } } } } } } } } ```