# X (Twitter) Trends Scraper (`mikolabs/x-twitter-trends-scraper`) Actor Get real-time and historical top trending topics, hashtags, and keywords from X.com for any of 35 countries — or a combined Global feed with lighting fast speed at cheapest - 0.05 per 1000 results. - **URL**: https://apify.com/mikolabs/x-twitter-trends-scraper.md - **Developed by:** [mikolabs](https://apify.com/mikolabs) (community) - **Categories:** Social media, News, Automation - **Stats:** 11 total users, 7 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $0.05 / 1,000 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.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 ## X (Twitter) Trends Scraper **Get real-time and historical top trending topics, hashtags, and keywords from X.com for any of 35 countries — or a combined Global feed with lighting fast speed at cheapest - 0.05 per 1000 results.** This Actor connects directly to the same internal API that X.com uses to load its Explore → Trending page. Every result you get is exactly what a real user in that country would see right now, or at any point in the last 100 hours. --- ### What You Get Each run returns up to **30 ranked trends** per country snapshot, or up to **150 trends** for the Global feed. Every trend record includes: - **Rank** — position 1–30 in the trending list - **Trend name** — the exact hashtag or topic (e.g. `#GeneralConference`, `Walter Reed`, `Happy Easter`) - **Category** — the content type X assigns it: `Sports`, `Music`, `Politics`, `Entertainment industry`, `Business and finance`, `Trending` (general), etc. - **Context** — the full domain string X shows users, e.g. `"Sports · Trending"` or `"Trending in United States"` - **Status** — `Live` for real-time fetches, or `1 hour ago` / `6 hours ago` etc. for historical snapshots - **Age (hours)** — how many hours ago the snapshot was recorded - **Recorded At (UTC)** — exact ISO timestamp of when the data was captured **Example output record:** ```json { "rank": 3, "trend": "Happy Easter", "category": "Entertainment industry", "domain_context": "Entertainment industry · Trending", "status": "Live", "age": 0, "time": "2025-04-05T10:00:00.000Z" } ```` You can download the full dataset in **JSON, CSV, HTML, or Excel** from the Apify Console Output tab. *** ### Supported Countries (35 + Global) The Actor routes its residential proxy through the country you select, so you receive the trending topics that users in that country actually see — not a generic feed. | Region | Countries | |--------|-----------| | 🌍 **Global** | Combined feed of worldwide trends (up to 150 topics) | | 🇺🇸 North America | United States, Canada, Mexico | | 🇬🇧 Europe | United Kingdom, France, Germany, Italy, Spain, Portugal, Netherlands, Denmark, Austria, Belgium, Switzerland, Greece | | 🇷🇺 Eastern Europe & Middle East | Russian Federation, Turkey, Israel, United Arab Emirates, Saudi Arabia, Egypt | | 🌏 Asia-Pacific | Korea, Singapore, Indonesia, Philippines, Viet Nam, Thailand, Australia, Japan | | 🌍 Africa | Nigeria, Kenya, South Africa | | 🌎 Latin America | Argentina, Brazil, Mexico | **How country targeting works:** When you select `Japan`, the residential proxy routes your request through a Japanese IP address. X.com returns the trending topics it shows Japanese users — local language, regional news, and country-specific events included. Selecting `Global` aggregates trending data from all 34 country feeds into a single deduplicated list of up to 150 topics. *** ### How to Use It #### Step 1 — Configure your run Open the Actor input form and select your options: | Input Field | What it does | Default | |-------------|-------------|---------| | **Country** | Which country's trending feed to fetch | United States | | **Live** | Fetch what's trending right now | On | | **1 hour ago** | Include the stored snapshot from 1 hour ago | Off | | **3 hours ago** | Include the stored snapshot from 3 hours ago | Off | | **6 hours ago** | Include the stored snapshot from 6 hours ago | Off | | **12 hours ago** | Include the stored snapshot from 12 hours ago | Off | | **24 hours ago** | Include the stored snapshot from 24 hours ago | Off | | **2 days ago** | Include the stored snapshot from 48 hours ago | Off | | **3 days ago** | Include the stored snapshot from 72 hours ago | Off | You can enable **multiple time periods at once**. The output will contain one clearly labeled snapshot per period selected — useful for comparing what was trending now vs 6 hours ago vs yesterday. #### Step 2 — Run and get results Click **Start**. The Actor completes in under 30 seconds. Results appear in the Output tab immediately. *** ### Input Examples **Live trends for the UK right now:** ```json { "country": "United Kingdom", "live": true } ``` **Live + compare to 6 hours ago and 24 hours ago in Japan:** ```json { "country": "Japan", "live": true, "hour6": true, "hour24": true } ``` **Historical only — what was trending in Brazil 3 days ago:** ```json { "country": "Brazil", "live": false, "day3": true } ``` **Global feed — live trends + 24-hour comparison:** ```json { "country": "Global", "live": true, "hour24": true } ``` ### Use Cases **Media monitoring** — Track which topics are dominating conversation in specific countries right now vs 24 hours ago. Spot emerging stories before they peak. **Marketing & PR** — Identify trending hashtags and topics in your target market before launching campaigns. Join relevant conversations at the right moment. **Competitive intelligence** — See which brands, events, and topics are gaining traction in markets you operate in or plan to enter. **Academic & social research** — Build longitudinal datasets of trending topics across countries and time periods for analysis. **Content strategy** — Discover what your audience is talking about in real time to inform what content to create and when to publish it. **Financial research** — Monitor trending tickers, economic terms, and market-relevant topics across different geographies. **News & journalism** — Get a country-level pulse on what the public is discussing at any given moment across 35 markets. *** ### Data Accuracy This Actor uses **X.com's own internal API** — the exact same endpoint that your browser calls when you open the Explore → Trending page. The data returned is bit-for-bit identical to what you would see if you opened X.com yourself while physically located in the selected country. Geo-targeted to your selection - `Global` → aggregates all 34 country feeds into one deduplicated list There is no sampling, filtering, or estimation involved. You get the full ranked list exactly as X presents it. *** ### Cost Each run makes one authenticated API call per country. A single live fetch for one country completes in under 10 seconds. | Mode | API calls | Approximate cost | |------|-----------|------------------| | Live — 1 country | 1 | < $0.01 | Actual costs depend on your Apify plan. *** ### Frequently Asked Questions **Do I need X Premium or a developer account?** No. The Actor uses your regular X.com session cookies — the same ones your browser uses to keep you logged in. Any standard free or paid X account works. **How fresh is the live data?** Live mode fetches data the moment you click Run. What you receive is exactly what X shows to users in the selected country at that instant. **Why might I see fewer than 30 trends?** X occasionally returns fewer than 30 trends for some countries, particularly smaller markets, or during low-activity periods. The Actor returns whatever X provides without padding or estimation. **Is this legal?** This Actor accesses publicly visible trending data using your own authenticated X.com session. Trending topics are publicly displayed on X.com's Explore page and visible to any logged-in user. Always use responsibly and in accordance with [X's Terms of Service](https://x.com/tos). *** ### ⚠️ X.com Changes X.com frequently modifies its internal structure without public notice — including GraphQL endpoint IDs, feature flag parameters, response schemas, and authentication requirements. **If this Actor stops returning results or starts throwing errors**, it is most likely because X.com has changed one of the following: - The `timelineId` for the trending feed - Required request headers or `features` parameters - The JSON structure of the trending response #### Please raise an issue Open the **Issues** tab on this Actor's page and include: 1. The date you noticed the problem 2. The country you were querying 3. The error message from the Actor run log 4. A note of whether live or historical data is affected Community reports are the fastest way to catch breaking changes. We aim to ship fixes within **24–48 hours** of a confirmed X.com API change. *** ### Support & Custom Integrations For bugs or broken results — use the **Issues** tab on this Actor's page. For high-volume setups, additional country coverage, custom data pipelines, or white-label integrations — reach out via the Issues tab with your requirements. # Actor input Schema ## `country` (type: `string`): Select the country or Global feed to query. ## `live` (type: `boolean`): Fetch live trends right now. ## `hour1` (type: `boolean`): Include the stored UTC snapshot from 1 hour ago. ## `hour3` (type: `boolean`): Include the stored UTC snapshot from 3 hours ago. ## `hour6` (type: `boolean`): Include the stored UTC snapshot from 6 hours ago. ## `hour12` (type: `boolean`): Include the stored UTC snapshot from 12 hours ago. ## `hour24` (type: `boolean`): Include the stored UTC snapshot from 24 hours ago. ## `day2` (type: `boolean`): Include the stored UTC snapshot from 48 hours ago. ## `day3` (type: `boolean`): Include the stored UTC snapshot from 72 hours ago. ## Actor input object example ```json { "country": "United States", "live": true, "hour1": false, "hour3": false, "hour6": false, "hour12": false, "hour24": false, "day2": false, "day3": false } ``` # Actor output Schema ## `dataset` (type: `string`): No description ## `output` (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 = { "live": true }; // Run the Actor and wait for it to finish const run = await client.actor("mikolabs/x-twitter-trends-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 = { "live": True } # Run the Actor and wait for it to finish run = client.actor("mikolabs/x-twitter-trends-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 '{ "live": true }' | apify call mikolabs/x-twitter-trends-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=mikolabs/x-twitter-trends-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "X (Twitter) Trends Scraper", "description": "Get real-time and historical top trending topics, hashtags, and keywords from X.com for any of 35 countries — or a combined Global feed with lighting fast speed at cheapest - 0.05 per 1000 results.", "version": "0.0", "x-build-id": "da0dyGQimsJxP9CQ7" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/mikolabs~x-twitter-trends-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-mikolabs-x-twitter-trends-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/mikolabs~x-twitter-trends-scraper/runs": { "post": { "operationId": "runs-sync-mikolabs-x-twitter-trends-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/mikolabs~x-twitter-trends-scraper/run-sync": { "post": { "operationId": "run-sync-mikolabs-x-twitter-trends-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": { "country": { "title": "Country", "enum": [ "Global", "United States", "Canada", "Mexico", "United Kingdom", "France", "Germany", "Italy", "Spain", "Portugal", "Netherlands", "Denmark", "Austria", "Belgium", "Switzerland", "Greece", "Russian Federation", "Turkey", "Korea", "Singapore", "Indonesia", "Philippines", "Viet Nam", "Thailand", "Australia", "Israel", "United Arab Emirates", "Saudi Arabia", "Argentina", "Brazil", "Egypt", "Nigeria", "Kenya", "South Africa", "Japan" ], "type": "string", "description": "Select the country or Global feed to query.", "default": "United States" }, "live": { "title": "Live", "type": "boolean", "description": "Fetch live trends right now.", "default": true }, "hour1": { "title": "1 hour ago", "type": "boolean", "description": "Include the stored UTC snapshot from 1 hour ago.", "default": false }, "hour3": { "title": "3 hours ago", "type": "boolean", "description": "Include the stored UTC snapshot from 3 hours ago.", "default": false }, "hour6": { "title": "6 hours ago", "type": "boolean", "description": "Include the stored UTC snapshot from 6 hours ago.", "default": false }, "hour12": { "title": "12 hours ago", "type": "boolean", "description": "Include the stored UTC snapshot from 12 hours ago.", "default": false }, "hour24": { "title": "24 hours ago", "type": "boolean", "description": "Include the stored UTC snapshot from 24 hours ago.", "default": false }, "day2": { "title": "2 days ago", "type": "boolean", "description": "Include the stored UTC snapshot from 48 hours ago.", "default": false }, "day3": { "title": "3 days ago", "type": "boolean", "description": "Include the stored UTC snapshot from 72 hours ago.", "default": false } } }, "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 } } } } } } } } } } ```