# X Search & Discovery Scraper (`chronometrica/x-search-scraper`) Actor Find public X posts from keywords, hashtags, mentions, advanced queries, profile filters, engagement filters, and date ranges. - **URL**: https://apify.com/chronometrica/x-search-scraper.md - **Developed by:** [Chronometrica](https://apify.com/chronometrica) (community) - **Categories:** Social media, Agents, Automation - **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.80 / 1,000 x search results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. 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/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.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/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 ## X Search & Discovery Scraper ### ๐Ÿ”Ž What does X Search & Discovery Scraper do? X Search & Discovery Scraper finds up to 1,000 public X posts per query from keywords, hashtags, mentions, profiles, date ranges, engagement filters, and other advanced X search operators. Use it for continuous news monitoring, social listening, creator discovery, brand mentions, competitor research, alerts, bots, and scheduled discovery feeds. Run several searches at once. Every result keeps both the input query and the exact executed query, so rows never lose the keyword or filter that found them. Each dataset row represents one public X post returned by one executed query. The same post may appear once for query A and once for query B because those are two useful search observations. Repeated appearances inside one query are removed. This Actor uses logged-out public X data. It does not accept account cookies, passwords, or private tokens. It does not access private posts or promise a complete archive of any profile. With X Search & Discovery Scraper, you can: - ๐Ÿ” Search keywords, phrases, hashtags, and mentions. - ๐Ÿ‘ค Find posts with filters such as `from:OpenAI`. - ๐Ÿ“ˆ Use public engagement filters such as `min_faves:100`. - ๐Ÿ—“๏ธ Limit discovery to a date range. - ๐Ÿงญ Compare Latest posts, Top posts, Photos, and Videos search types. - ๐Ÿ” Run up to 20 independent searches in one job. - ๐Ÿท๏ธ Keep exact query lineage on every saved post. - ๐Ÿ“ฃ Remove promoted results from the saved dataset. - ๐Ÿ“ฆ Export rows as JSON, JSONL, CSV, Excel, XML, RSS, or HTML. ### ๐Ÿ“ฆ What X search data can I extract? One row is one post returned by one executed query. | Data group | Example fields | | ----------------- | ------------------------------------------------------------- | | ๐Ÿ” Query context | `inputQuery`, `executedQuery`, `searchMode`, `resultPosition` | | ๐Ÿ”— Post identity | `postId`, `postUrl`, `conversationId` | | ๐Ÿงพ Post details | `text`, `createdAt`, hashtags, mentions, and links | | ๐Ÿ‘ค Author | `authorId`, `authorHandle`, `authorName`, `authorUrl` | | ๐Ÿ” Relationships | reply, quote, and repost IDs and flags | | ๐Ÿ“Š Public metrics | `likes`, `reposts`, `replies`, `views`, `bookmarks` | | ๐Ÿ–ผ๏ธ Media | photos, videos, preview URLs, and alt text | | ๐Ÿ•’ Observation | `observedAt` | Missing public values stay `null`. They are not guessed or changed to fake zeroes. ### โš™๏ธ Can I use this Actor through an API? Yes. Run it in Apify Console or connect it through: - Apify API - Python SDK - JavaScript SDK - Webhooks - Scheduled Tasks - Apify integrations ### ๐ŸŽฏ Why search public X posts? | Use case | How the data helps | | ------------------------ | ------------------------------------------------------- | | ๐Ÿ“ฃ Brand monitoring | Find public posts that mention a brand or product. | | ๐Ÿง‘โ€๐ŸŽจ Creator discovery | Find people posting about a market or topic. | | ๐Ÿ”ฅ Trend research | Compare visible conversations and engagement. | | ๐Ÿ•ต๏ธ Competitor monitoring | Watch public discussion around competing products. | | ๐Ÿงฑ Data-pipeline seeding | Feed discovered post IDs into metrics or research jobs. | ### ๐Ÿ’ต Pricing event One paid search result means one real public post row returned by one executed query. Empty pages, promoted results, repeats, date mismatches, and run-summary records are not paid search results. Platform usage is included. A small Actor start event also applies, as shown in the Store pricing table. Use `maxItemsPerQuery` to control the possible result count. With several queries, each query receives its own cap. The Actor stops saving results when the run reaches your maximum charge. ### ๐Ÿš€ How do I use X Search & Discovery Scraper? 1. Open **X Search & Discovery Scraper** in Apify Console. 2. Add one or more search queries. 3. Choose Latest posts, Top posts, Photos, or Videos. 4. Set the number of posts to save per query. 5. Add an optional start or end date. 6. Click **Start**. 7. Open the **Output** tab to inspect the dataset and run summary. ### โฌ‡๏ธ Input ```json { "queries": ["artificial intelligence", "#buildinpublic"], "searchMode": "latest", "maxItemsPerQuery": 100, "startTime": "2026-01-01", "endTime": "2026-06-30" } ```` | Setting | What it controls | | ------------------ | ------------------------------------------------------------------- | | `queries` | 1 to 20 simple or advanced X search queries. | | `searchMode` | Latest posts, Top posts, Photos, or Videos. | | `maxItemsPerQuery` | Saves up to 1,000 rows for each query after exclusions and repeats. | | `startTime` | Optional first calendar date to include. | | `endTime` | Optional last calendar date to include. | Safety limits and pacing are handled automatically. They are not exposed as input settings. #### ๐Ÿงญ Simple query examples | Goal | Query example | | --------------------- | ------------------------- | | ๐Ÿ” Topic search | `artificial intelligence` | | ๐Ÿ’ฌ Exact phrase | `"open source AI"` | | #๏ธโƒฃ Hashtag tracking | `#buildinpublic` | | ๐Ÿ“ฃ Mention monitoring | `@OpenAI` | #### ๐Ÿงฐ Optional advanced operators Start with a simple query. Add an operator only when you need to narrow the results. | Goal | Operator example | | ------------------------- | ---------------- | | ๐Ÿ‘ค Posts from one profile | `from:OpenAI` | | ๐Ÿ“ˆ Minimum public likes | `min_faves:100` | | ๐Ÿšซ Exclude one profile | `-from:OpenAI` | | ๐Ÿ–ผ๏ธ Require attached media | `filter:media` | You can combine a normal search with operators. For example, `AI from:OpenAI min_faves:100` means posts about AI from `@OpenAI` with at least 100 public likes. Optional `startTime` and `endTime` values are inclusive. The Actor adds visible date filters to the executed query and checks each returned post date again. Do not also add `since:` or `until:` operators to a query when using the date fields. ### โฌ†๏ธ Output sample ```json { "platform": "x", "discoverySource": "x_search", "inputQuery": "artificial intelligence", "executedQuery": "artificial intelligence since:2026-01-01 until:2026-07-01", "searchMode": "Latest", "resultPosition": 1, "postId": "2077446718728425686", "postUrl": "https://x.com/OpenAI/status/2077446718728425686", "text": "Example post", "createdAt": "2026-06-30T12:00:00.000Z", "authorId": "4398626122", "authorHandle": "@OpenAI", "authorName": "OpenAI", "authorUrl": "https://x.com/OpenAI", "likes": 8000, "reposts": 700, "replies": 400, "views": 1600000, "bookmarks": 2000, "observedAt": "2026-07-17T12:00:00.000Z" } ``` #### ๐Ÿ“Œ Run summary The `OUTPUT` record reports: - queries queued and executed; - rows saved; - repeats inside each query; - date exclusions; - promoted results seen and excluded; - a safe stop reason and result for every query. ### ๐Ÿงญ Query fields explained `inputQuery` is the query supplied by the user. `executedQuery` is the exact query sent after optional date operators are added. `resultPosition` is the post's observed position inside that executed query. It is not a permanent rank or a quality score. ### ๐Ÿšฆ Search quality and stop reasons Only public posts with a stable post ID and author identity become dataset rows. The run summary separates: - posts returned by X; - rows saved; - repeats skipped inside a query; - posts outside the requested time range; - promoted results removed; - source exhaustion, safety limits, and public source errors. This makes a short result set explainable. Fewer rows than requested does not automatically mean the run failed. ### ๐Ÿ”’ Source boundary This Actor reads logged-out public X data. It stops safely when that public data is unavailable. It does not: - use an X account or account pool; - accept cookies, passwords, or private tokens; - access private or protected posts; - solve login or challenge screens; - promise complete profile history. ### โš ๏ธ Limits and interpretation - The Actor saves up to 1,000 posts per query. - The cap is not a promise. X may stop returning matches before the cap is reached. - X chooses which posts appear and how they are ranked. Fewer rows than the cap can be correct. - Search results are discovery observations, not a complete profile archive. - Promoted results are counted in the run summary and excluded from the dataset. - A source limit, block, or rate limit may stop collection early. - Deleted, private, age-gated, or region-limited posts may be missing. - X can change its public surface, so later runs may need an Actor update. ### โ“ FAQ #### Does this Actor need an X login, cookie, or API key? No. It reads logged-out public X data. #### Can I search one profile? Yes. Use an advanced query such as `from:OpenAI`. This finds posts returned by X search. It does not promise the profile's complete history. #### Why did I receive fewer posts than requested? The source may have fewer visible matches. Promoted posts, repeats, and posts outside the exact time range are also excluded. Check the run summary for the exact reason. #### How are duplicates handled? A post is saved once inside each executed query. The same post may be saved again for another query because that is a separate discovery observation. ### ๐Ÿ›Ÿ Support For help, share the run ID, input query, expected result, and actual result. Never share passwords, cookies, or private tokens. Use public data in line with the law, X rules, and Apify rules. # Actor input Schema ## `queries` (type: `array`): Add 1 to 20 searches. Each list item runs separately and gets its own result limit. Start with words, a phrase, a hashtag, or a mention. Advanced filters are optional. ## `searchMode` (type: `string`): Choose the kind of results to return. Latest posts favors recent posts, Top posts follows X relevance, and Photos or Videos limits the result type. ## `maxItemsPerQuery` (type: `integer`): Save up to this many posts from each search. Default: 100. Range: 1 to 1,000. For example, 5 searches with a limit of 100 can return up to 500 rows. X may return fewer. ## `startTime` (type: `string`): Optional first date to include. Leave blank to search without a start date. Do not also add since: to the search query. ## `endTime` (type: `string`): Optional last date to include. Leave blank to search without an end date. Do not also add until: to the search query. ## Actor input object example ```json { "queries": [ "artificial intelligence" ], "searchMode": "latest", "maxItemsPerQuery": 100 } ``` # Actor output Schema ## `dataset` (type: `string`): No description ## `summary` (type: `string`): No description # 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 = { "queries": [ "artificial intelligence" ] }; // Run the Actor and wait for it to finish const run = await client.actor("chronometrica/x-search-scraper").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 = { "queries": ["artificial intelligence"] } # Run the Actor and wait for it to finish run = client.actor("chronometrica/x-search-scraper").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 '{ "queries": [ "artificial intelligence" ] }' | apify call chronometrica/x-search-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=chronometrica/x-search-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "X Search & Discovery Scraper", "description": "Find public X posts from keywords, hashtags, mentions, advanced queries, profile filters, engagement filters, and date ranges.", "version": "0.1", "x-build-id": "LVFJ1udGHIMqOko8X" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/chronometrica~x-search-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-chronometrica-x-search-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/chronometrica~x-search-scraper/runs": { "post": { "operationId": "runs-sync-chronometrica-x-search-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/chronometrica~x-search-scraper/run-sync": { "post": { "operationId": "run-sync-chronometrica-x-search-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", "required": [ "queries" ], "properties": { "queries": { "title": "Search queries", "minItems": 1, "maxItems": 20, "uniqueItems": true, "type": "array", "description": "Add 1 to 20 searches. Each list item runs separately and gets its own result limit. Start with words, a phrase, a hashtag, or a mention. Advanced filters are optional.", "items": { "type": "string" } }, "searchMode": { "title": "Search type", "enum": [ "latest", "top", "photos", "videos" ], "type": "string", "description": "Choose the kind of results to return. Latest posts favors recent posts, Top posts follows X relevance, and Photos or Videos limits the result type.", "default": "latest" }, "maxItemsPerQuery": { "title": "Maximum posts per query", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Save up to this many posts from each search. Default: 100. Range: 1 to 1,000. For example, 5 searches with a limit of 100 can return up to 500 rows. X may return fewer.", "default": 100 }, "startTime": { "title": "Start date", "type": "string", "description": "Optional first date to include. Leave blank to search without a start date. Do not also add since: to the search query." }, "endTime": { "title": "End date", "type": "string", "description": "Optional last date to include. Leave blank to search without an end date. Do not also add until: to the search query." } } }, "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 } } } } } } } } } } ```