# X Twitter Trends Scraper - Country Trends API (`khadinakbar/x-twitter-trends-scraper`) Actor Scrape X Twitter trends by country or worldwide with ranks, hashtags, WOEID, source links, X search URLs, and MCP-ready rows. $0.003/trend plus usage. - **URL**: https://apify.com/khadinakbar/x-twitter-trends-scraper.md - **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community) - **Categories:** Social media, News, AI - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 trend scrapeds This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. 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 Twitter Trends Scraper Scrape live X/Twitter trending topics for countries or worldwide from public trend pages. The actor returns one clean JSON row per trend with rank, trend type, source URL, X search URL, WOEID when available, UTC snapshot time, and compact rank-history metadata. Use it for social listening, newsroom monitoring, campaign timing, regional trend alerts, and AI-agent workflows that need a current list of public X topics without asking users for cookies. ### When To Use This Actor Use this actor when you need: - Current X/Twitter trends for worldwide or country-level locations - Top hashtags, cashtags, and keyword topics in a normalized dataset - UTC trend snapshots for monitoring or scheduled runs - A no-cookie trend feed for dashboards, alerts, or MCP clients - Public source links plus direct X search URLs for each trend Do not use this actor for tweet scraping, profile scraping, replies, followers, or X search results. Use a dedicated X/Twitter tweet, profile, replies, or search scraper for those jobs. ### Output | Field | Example | Description | | --- | --- | --- | | `locationName` | `United States` | Country or worldwide source location | | `locationWoeid` | `23424977` | WOEID exposed by the trend page | | `snapshotAt` | `2026-07-15T15:00:00.000Z` | UTC trend snapshot represented by the page | | `position` | `1` | Rank in the location trend table | | `trendName` | `#BuildInPublic` | Hashtag, cashtag, or keyword topic | | `trendType` | `hashtag` | `hashtag`, `cashtag`, or `keyword` | | `dailyTweetScore` | `123` | Source-page daily score when available | | `longestTrendingText` | `4 hours` | Duration from the source page when available | | `rankHistoryLabel` | `...last 8 hours` | Compact source chart description | | `trendUrl` | `https://getdaytrends.com/...` | Public trend detail URL | | `xSearchUrl` | `https://x.com/search?...` | Direct X/Twitter search URL | `tweetVolume` is included as a stable nullable field. Public country trend pages do not always expose tweet volume, so it can be `null`. ### Pricing This actor uses Pay per event plus platform usage. Event charges are: - Actor start: `$0.00005` - Trend scraped: `$0.003` per trend record saved to the dataset Typical examples: | Input | Records | Event charge | | --- | ---: | ---: | | `["worldwide"]`, 25 trends | 25 | about `$0.075` | | `["united-states"]`, 50 trends | 50 | about `$0.150` | | 5 locations, 50 trends each | 250 | about `$0.750` | Apify platform usage is billed separately under Pay per event plus usage. The actor logs the maximum possible event charge before it starts saving rows. ### Input ```json { "locations": ["worldwide", "united-states", "pakistan"], "maxTrendsPerLocation": 50, "dedupeTrends": true, "includeRankHistory": true } ```` `locations` accepts country names, slugs, or GetDayTrends URLs: - `worldwide` - `United States` - `pakistan` - `https://getdaytrends.com/united-kingdom/` ### API Usage #### JavaScript ```javascript import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' }); const run = await client.actor('khadinakbar/x-twitter-trends-scraper').call({ locations: ['worldwide', 'united-states'], maxTrendsPerLocation: 25, }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items[0]); ``` #### Python ```python from apify_client import ApifyClient client = ApifyClient('YOUR_APIFY_TOKEN') run = client.actor('khadinakbar/x-twitter-trends-scraper').call(run_input={ 'locations': ['worldwide', 'pakistan'], 'maxTrendsPerLocation': 25, }) items = list(client.dataset(run['defaultDatasetId']).iterate_items()) print(items[0]) ``` ### MCP And AI Agent Use This actor is designed for Apify MCP clients. A good tool call is narrow: ask for locations and a maximum number of trends, then read the dataset rows. Example agent requests: - "Get the top 25 X trends for Pakistan and the United States." - "Monitor worldwide X trends every hour and alert me when AI topics appear." - "Compare hashtags trending in India, Japan, and the United Kingdom." Each dataset row is flat, stable, and small enough for agents to sample safely. ### Related Actors Use these dedicated actors when you need adjacent X/Twitter or trend data: - [X Twitter Search Scraper](https://apify.com/khadinakbar/x-twitter-search-scraper) - [X Tweet Scraper](https://apify.com/khadinakbar/x-tweet-scraper) - [X Twitter Profile Scraper](https://apify.com/khadinakbar/x-twitter-profile-scraper) - [X Twitter Replies Scraper](https://apify.com/khadinakbar/x-twitter-replies-scraper) - [X Tweet Engagement Scraper](https://apify.com/khadinakbar/x-tweet-engagement-scraper) - [Twitter Profile Followers Scraper](https://apify.com/khadinakbar/twitter-profile-followers-scraper) - [TikTok Trending Hashtags Scraper](https://apify.com/khadinakbar/tiktok-trending-hashtags-scraper) - [TikTok Trending Videos Scraper](https://apify.com/khadinakbar/tiktok-trending-videos-scraper) - [YouTube Trending Videos Scraper](https://apify.com/khadinakbar/youtube-trending-videos-scraper) - [Google Trends Scraper](https://apify.com/khadinakbar/google-trends-scraper) - [Reddit Trends Scraper](https://apify.com/khadinakbar/reddit-trends-scraper) ### FAQ #### Is this actor affiliated with X Corp? No. It reads public trend pages and creates normalized records for analysis. It is not affiliated with, endorsed by, or sponsored by X Corp. #### Does it require cookies or an X login? No. The default mode uses public trend pages and does not ask users for cookies, passwords, or browser sessions. #### Can it scrape city-level trends? This version focuses on worldwide and country-level trend pages. If you need city-level WOEID support, use an official X API bearer-token workflow or a provider that explicitly exposes city trends. #### Can it scrape historical trend snapshots? This version focuses on live/current worldwide and country-level trend pages. Historical pages were not reliable enough in source testing to advertise as a supported input. #### Can I use X Twitter Trends Scraper through an MCP Server? Yes. Run it through the Apify MCP Server and read the dataset output. The input schema uses clear location and limit fields so agents can call it directly. #### Is scraping X/Twitter trends legal? This actor extracts public trend-page information. You are responsible for using the data in compliance with applicable laws, platform rules, and privacy requirements. #### How can I report an issue? Open the Issues tab on the actor page with the location, input JSON, and run ID. # Actor input Schema ## `locations` (type: `array`): Use this when you need current X/Twitter trends for one or more countries or worldwide. Accepts names, slugs, or public GetDayTrends URLs such as "United States", "pakistan", or "https://getdaytrends.com/united-kingdom/". Defaults to \["worldwide", "united-states"] and supports up to 50 locations per run. This is not a city-radius search or an X profile/tweet scraper. ## `maxTrendsPerLocation` (type: `integer`): Use this when you need to cap the number of trends returned for each location. A value like 25 returns the top 25 rows from each location page. Defaults to 50 with a hard maximum of 50 because the source trend page normally exposes the top 50. This is not a total run cap across all locations. ## `dedupeTrends` (type: `boolean`): Use this when you want one row per trend name per location. Defaults to true and skips duplicate rows if the upstream page repeats a trend. Set false only for diagnostics when comparing raw page rows. This does not dedupe the same trend across different countries. ## `includeRankHistory` (type: `boolean`): Use this when you want compact rank-history metadata from the page sparkline. Defaults to true and stores the source chart title plus raw SVG points when available. Disable it for the smallest possible dataset rows. This does not fetch per-trend detail pages. ## Actor input object example ```json { "locations": [ "worldwide", "united-states" ], "maxTrendsPerLocation": 50, "dedupeTrends": true, "includeRankHistory": true } ``` # Actor output Schema ## `dataset` (type: `string`): Dataset API URL containing one normalized row per X/Twitter trend. ## `output` (type: `string`): Compact OUTPUT record with outcome, counts, and warnings. ## `runSummary` (type: `string`): Detailed RUN\_SUMMARY record for diagnostics and release verification. # 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 = { "locations": [ "worldwide", "united-states" ] }; // Run the Actor and wait for it to finish const run = await client.actor("khadinakbar/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 = { "locations": [ "worldwide", "united-states", ] } # Run the Actor and wait for it to finish run = client.actor("khadinakbar/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 '{ "locations": [ "worldwide", "united-states" ] }' | apify call khadinakbar/x-twitter-trends-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=khadinakbar/x-twitter-trends-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "X Twitter Trends Scraper - Country Trends API", "description": "Scrape X Twitter trends by country or worldwide with ranks, hashtags, WOEID, source links, X search URLs, and MCP-ready rows. $0.003/trend plus usage.", "version": "1.0", "x-build-id": "U8DmXdNXokp1Gf6Fe" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/khadinakbar~x-twitter-trends-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-khadinakbar-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/khadinakbar~x-twitter-trends-scraper/runs": { "post": { "operationId": "runs-sync-khadinakbar-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/khadinakbar~x-twitter-trends-scraper/run-sync": { "post": { "operationId": "run-sync-khadinakbar-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", "required": [ "locations" ], "properties": { "locations": { "title": "Locations", "minItems": 1, "maxItems": 50, "type": "array", "description": "Use this when you need current X/Twitter trends for one or more countries or worldwide. Accepts names, slugs, or public GetDayTrends URLs such as \"United States\", \"pakistan\", or \"https://getdaytrends.com/united-kingdom/\". Defaults to [\"worldwide\", \"united-states\"] and supports up to 50 locations per run. This is not a city-radius search or an X profile/tweet scraper.", "items": { "type": "string" }, "default": [ "worldwide", "united-states" ] }, "maxTrendsPerLocation": { "title": "Max trends per location", "minimum": 1, "maximum": 50, "type": "integer", "description": "Use this when you need to cap the number of trends returned for each location. A value like 25 returns the top 25 rows from each location page. Defaults to 50 with a hard maximum of 50 because the source trend page normally exposes the top 50. This is not a total run cap across all locations.", "default": 50 }, "dedupeTrends": { "title": "Dedupe trends per location", "type": "boolean", "description": "Use this when you want one row per trend name per location. Defaults to true and skips duplicate rows if the upstream page repeats a trend. Set false only for diagnostics when comparing raw page rows. This does not dedupe the same trend across different countries.", "default": true }, "includeRankHistory": { "title": "Include rank history sparkline", "type": "boolean", "description": "Use this when you want compact rank-history metadata from the page sparkline. Defaults to true and stores the source chart title plus raw SVG points when available. Disable it for the smallest possible dataset rows. This does not fetch per-trend detail pages.", "default": true } } }, "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 } } } } } } } } } } ```