# X/Twitter Preset Trends Scraper (`simoit/x-twitter-preset-trends-scrapper`) Actor Preset X trend feeds from Explore tabs like news, sports, and entertainment - **URL**: https://apify.com/simoit/x-twitter-preset-trends-scrapper.md - **Developed by:** [simoit](https://apify.com/simoit) (community) - **Categories:** Social media, News, Automation - **Stats:** 7 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.15 / 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 web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. 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. - **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use). - **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`. - **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`. - **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`. - **Any other language** — 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 ## Trends Scraper ![SIMO IT logo](https://simoit.tech/favicon.ico) Work with preset X trend feeds from selected Explore tabs. This Actor can list preset trend timelines, fetch tweets for one concrete trend topic, and fetch relevant users for that trend. ### About SIMO IT SIMO IT builds practical social data products that support fast insight loops for marketing, PR, and growth teams. ### Features - collect posts from selected preset trend timelines - follow preset categories like `trending`, `news`, `sport`, and `entertainment` - preset categories map to X Explore tab feeds such as: - `news`: - `sport`: - `entertainment`: - fetch tweets for one concrete trend topic using numeric `trendId` - collect `TrendRelevantUsers` for one concrete trend topic by numeric trend rest\_id - resolve a trend by human-readable `trendQuery` when you do not have the numeric id yet - keep a display-friendly `trend_ref` on trend-aware tweet and relevant-user outputs - monitor topic momentum and context - paginate for deeper trend analysis ### Use cases - trendwatching and social listening - real-time content planning - spotting opportunities for rapid PR and marketing reactions ### Output Preset trend-feed content that can be used immediately in analysis, planning, and decision workflows. Note: backend endpoint returns an envelope: `{ data: [...], page, limit, has_next }`. This Actor pushes only records from `data[]` to the dataset. ### How to use 1. Start with `What do you want to fetch?`. 2. For `Discover trends`, `category` defaults to `trending`, but you can still choose `news`, `sport`, or `entertainment`. 3. For tweets or relevant users, leave `category` empty and put the numeric value into `trendId`, or use `trendQuery` if you only have a readable topic name or hashtag. 4. You can get that numeric id from a returned deep link such as `twitter://trending/2025383938727051697`. 5. Do not use the top-level trend item `id` like `trend-Southampton Stun Arsenal 2-1 to Reach FA Cup Semis` when you need the raw rest\_id. Use the numeric value from `trend_url.url`, the helper field `trend_id`, or `trendQuery` for lookup. 6. For tweet runs, choose `Tweet feed`: `Latest` or `Top`. 7. In most cases you do not need to touch `Data mode` in the Advanced section. 8. `Data mode = auto` behaves differently depending on the target: `trending`, `news`, `sport`, `entertainment` return trend items, while a numeric `trendId` switches automatically to one concrete trend flow and returns tweets plus relevant users. 9. Configure pagination and caps as needed. Important: - this Actor works on preset trend categories, not the newer global-trending country/category feed - if you want the fuller country/category-based trends product, use - `category` is only for trends discovery - `trendId` is required for tweets and relevant users unless you provide `trendQuery` - `trendQuery` can be used instead of `trendId` when you only have a readable trend name or hashtag - if both are filled, the Actor prioritizes `trendId` - `trend_ref` is a display label for concrete tweet and relevant-user outputs - invalid user input is reported as a successful run with a clear `USER_ERROR_REPORT` in the default key-value store instead of a generic crash - dataset shape stays unchanged for existing clients; error details are written to key-value store and status message, not pushed as dataset records - each run stores a `RUN_REPORT` key in the default key-value store with counts, warnings, and structured debug events No technical setup is required from your side. Backend infrastructure is managed by SIMO IT. Need a custom plan, custom limits, or a tailored data workflow? Contact `contact@simoit.tech`. ### Related Actors - Need country and category feeds from the newer global-trending surface? Use [Global Trending Scraper](https://apify.com/simoit/x-twitter-trends-scrapper). - Need tweet search after discovering a trend topic? Use [Tweet Scraper](https://apify.com/simoit/x-twitter-search-tweets-scrapper). - Need to inspect what one account posted around a trend? Use [Profile Scraper](https://apify.com/simoit/x-twitter-profile-scrapper). - Need account metadata or follower graphs for relevant users? Use [User Scraper](https://apify.com/simoit/x-twitter-user-scrapper). ### Input - `inputTargetType` (string, recommended): Primary UI selector for the run intent. - `discover_trends`: list trends from one preset category - `trend_tweets`: fetch tweets for one concrete numeric trend id - `relevant_users`: fetch relevant users for one concrete numeric trend id - `trend_tweets_and_users`: fetch both datasets for one concrete numeric trend id - `trendId` (string, conditionally required): - for `trends`: preset category (`trending`, `news`, `sport`, `entertainment`) or another backend-supported custom identifier - for `tweets` and `relevant_users`: numeric trend rest\_id only, extracted from `trend_url.url` like `twitter://trending/2040024758503477259` - `trendQuery` (string, optional): Human-readable trend lookup term used when you do not have the numeric rest\_id yet. The backend resolves it against current preset trend feeds and returns the best match. - `trendName` (string, optional): Optional label stored together with returned tweets/users. - `sort` (string, optional, default: `latest`): Tweet timeline selection for one concrete trend. - `latest`: most recent tweets for the trend - `top`: top-ranked tweets for the trend - `category` (string, optional): Preset trend category: `trending`, `news`, `sport`, or `entertainment`. These are preset Explore-style feeds, not the newer global-trending categories. Use only for `discover_trends`. - `trendUrl` (string, optional): Single concrete X/Twitter trend URL. - `trendUrls` (string, optional): Batch concrete trend URLs (comma-separated or new lines). - `startUrls` (string, optional): Alias batch URL input (comma-separated or new lines). - `dataMode` (string, optional, default: `auto`): Advanced override. Usually leave it untouched. - `auto`: choose the right flow automatically from the provided target preset targets like `trending`, `news`, `sport`, and `entertainment` return trend items numeric `trendId` values or `trendQuery` values return tweets plus relevant users for that one concrete trend - `trends`: list current trends/posts from preset categories or another backend-supported custom identifier - `tweets`: fetch tweets for one concrete numeric trend id - `relevant_users`: list relevant users for one concrete numeric trend id - `both`: run both flows explicitly - `page` (integer, optional, default: `1`): Starting page number. - `limit` (integer, optional, default: `20`, max: `100`): Records per page. - `maxPages` (integer, optional, default: `1`): Number of pages to fetch starting from `page`. Example: `page=2` and `maxPages=5` fetches pages `2..6`. - `maxItems` (integer, optional): Hard cap for trend records. - `usersPage` (integer, optional, default: `1`): Starting page for trend relevant users. - `usersLimit` (integer, optional, default: `20`, max: `100`): Relevant users per page. - `usersMaxPages` (integer, optional, default: `1`): Number of relevant-user pages to fetch starting from `usersPage`. - `usersMaxItems` (integer, optional): Hard cap for trend relevant user records. #### Filters and pagination - trend target: `trendId`, `category`, `trendUrl`, `trendUrls`, `startUrls` - mode switch: `dataMode` - trend page controls: `page`, `limit`, `maxPages`, `maxItems` `maxPages` is relative to `page`, not an absolute final page number. - relevant users page controls: `usersPage`, `usersLimit`, `usersMaxPages`, `usersMaxItems` `usersMaxPages` is relative to `usersPage`. #### Example input Discover current sport trends: ```json { "inputTargetType": "discover_trends", "category": "sport", "limit": 10, "maxItems": 20 } ``` Fetch relevant users for one specific trend topic: ```json { "inputTargetType": "relevant_users", "trendId": "2025383938727051697", "usersLimit": 10, "usersMaxItems": 30 } ``` Fetch tweets for one specific trend topic: ```json { "inputTargetType": "trend_tweets", "trendId": "2025383938727051697", "sort": "latest", "limit": 10, "maxItems": 30 } ``` Let Auto infer one concrete trend flow from a numeric trend id: ```json { "inputTargetType": "discover_trends", "dataMode": "auto", "trendId": "2025383938727051697", "sort": "latest", "limit": 10 } ``` With the input above, the Actor does not try to discover preset trends. It treats the numeric `trendId` as one concrete trend and returns tweets plus relevant users automatically. Fetch both tweets and relevant users for one specific trend topic: ```json { "inputTargetType": "trend_tweets_and_users", "trendId": "2025383938727051697", "sort": "top", "limit": 10, "maxItems": 30, "usersLimit": 10, "usersMaxItems": 30 } ``` Do not use this for tweets: ```json { "inputTargetType": "trend_tweets", "category": "trending" } ``` Trend timeline items now include helper fields you can reuse directly: ```json { "trend_ref": "Vikings Receiver Rondale Moore Dies at 25 in Apparent Suicide (#2025383938727051697)", "trend_id": "2025383938727051697", "trend_slug": "trend-Vikings Receiver Rondale Moore Dies at 25 in Apparent Suicide", "trend_name": "Vikings Receiver Rondale Moore Dies at 25 in Apparent Suicide" } ``` Use `trend_id` as the numeric trend identifier for tweet and relevant-user runs. `trendQuery` is useful when you only have a readable topic name and want the Actor to resolve it first. `trend_ref` is the display label for tweet and relevant-user outputs. `trend_slug` is only a display-style slug derived from the trend item, for example `trend-Southampton Stun Arsenal 2-1 to Reach FA Cup Semis`. #### Example output ```json { "id": "trend-AI agents", "rank": null, "name": "Vikings Receiver Rondale Moore Dies at 25 in Apparent Suicide", "trend_url": { "url": "twitter://trending/2025383938727051697", "urlType": "DeepLink", "urlEndpointOptions": [] }, "trend_metadata": { "domain_context": null, "url": { "url": "twitter://trending/2025383938727051697", "urlType": "DeepLink", "urlEndpointOptions": [] }, "meta_description": null, "name": "Vikings Receiver Rondale Moore Dies at 25 in Apparent Suicide" }, "grouped_trends": [], "trend_id": "2025383938727051697", "trend_name": "Vikings Receiver Rondale Moore Dies at 25 in Apparent Suicide", "_type": "timelinetrend" } ``` #### Returned fields For trend timeline items: - `trend_id`: numeric trend identifier reused for tweet and relevant-user runs - `trend_name`: human-readable trend title - `trend_ref`: display label for concrete tweet and relevant-user outputs - `trend_slug`: display-style slug derived from the trend item - `trend_url.url`: deep link like `twitter://trending/2040024758503477259` - `trend_metadata`: extra trend metadata from X For tweet items: - `id`, `id_str`: tweet identifier - `trend_id`, `trend_name`, `trend_ref`: trend context attached by the Actor - `trend_slug`: display-style slug derived from the trend context - `url`, `date`, `user`, `rawContent`: core tweet fields - `replyCount`, `retweetCount`, `likeCount`, `quoteCount`: engagement counters - `media`, `viewCount`: media and reach signals when available For relevant-user items: - `id`, `id_str`: user identifier - `trend_id`, `trend_name`, `trend_ref`: trend context attached by the Actor - `trend_slug`: display-style slug derived from the trend context - `username`, `name`, `followersCount`, `friendsCount`, `verified`: key profile fields ```json { "id": 1899999999999999999, "trend_id": "2025383938727051697", "trend_name": "Vikings Receiver Rondale Moore Dies at 25 in Apparent Suicide", "trend_ref": "Vikings Receiver Rondale Moore Dies at 25 in Apparent Suicide (#2025383938727051697)", "user": { "username": "espn" }, "rawContent": "Vikings Receiver Rondale Moore Dies at 25 in Apparent Suicide ...", "_type": "snscrape.modules.twitter.Tweet" } ``` ```json { "id": 44196397, "trend_id": "2025383938727051697", "trend_name": "Vikings Receiver Rondale Moore Dies at 25 in Apparent Suicide", "trend_ref": "Vikings Receiver Rondale Moore Dies at 25 in Apparent Suicide (#2025383938727051697)", "username": "elonmusk", "name": "Elon Musk", "followersCount": 235240499, "friendsCount": 1288, "verified": true, "_type": "snscrape.modules.twitter.User" } ``` ### FAQ **Do I need my own backend or API setup?**\ No. This Actor is ready to run on Apify, and backend infrastructure is managed by SIMO IT. **Which values can I use for `trendId`?**\ For `trends`, use one of `trending`, `news`, `sport`, `entertainment`, or a raw timeline id. For tweets and `relevant_users`, use a numeric trend rest\_id from a concrete trend topic, or `trendQuery` if you only have the text label. **Can I collect trend data continuously?**\ Yes. Run the Actor on a schedule and paginate with `maxPages`. `maxPages` is relative to `page`, so `page=3` and `maxPages=2` means pages `3..4`. **How do I get the list of available categories first?**\ Use one of the built-in preset values shown in the Actor: `trending`, `news`, `sport`, `entertainment`. **How do I get the list of available trends first?**\ Run the Actor with one preset category. The returned trend items include a deep link such as `twitter://trending/2025383938727051697`. The numeric suffix is the trend id you can reuse. In the Actor output use `trend_id`. **How do I get users for a specific trend topic?**\ First fetch trends from a preset category, then take one concrete numeric `trend_id` from the returned items and run the Actor with that `trendId`. If you already know the readable trend name, you can also pass it through `trendQuery`. In normal usage `auto` is enough. **How do I get tweets for a specific trend topic?** First fetch trends from a preset category, then reuse `trend_id`. That numeric id is enough to fetch the tweet feed for that trend. Use `sort=latest` for the freshest posts or `sort=top` for the ranked feed. # Actor input Schema ## `inputTargetType` (type: `string`): Choose the run type first. Then fill only the fields relevant to that path. ## `dataMode` (type: `string`): Advanced override. Auto picks the right mode from your input. Preset values like trending/news/sport/entertainment return trend items. Numeric trendId switches Auto to one concrete trend flow and returns tweets plus relevant users. For concrete trend outputs the Actor also adds a display-friendly trend\_ref field. ## `trendId` (type: `string`): Numeric trend rest\_id for tweets and relevant users about one concrete trend, for example 2040024758503477259. You can extract it from trend\_url like twitter://trending/2040024758503477259. Returned tweets and relevant users include trend\_ref and trend\_slug for display. ## `trendQuery` (type: `string`): Optional display query for one concrete trend. Use this when you have a trend name, hashtag, or label instead of the numeric rest\_id. The Actor will resolve it to a current preset trend when possible. ## `trendName` (type: `string`): Optional label stored together with returned tweets/users. Not required for fetching tweets anymore. ## `sort` (type: `string`): Choose which tweet timeline to fetch for one concrete trend. Applies only to tweets. ## `category` (type: `string`): Optional preset trend timeline. Use this only for trends discovery, not for tweets or relevant users. ## `trendUrl` (type: `string`): Single concrete trend URL like https://x.com/i/trends/2039438188637196629. ## `trendUrls` (type: `string`): Optional concrete x.com/twitter.com trend URLs (comma-separated or new lines). ## `startUrls` (type: `string`): Alias for concrete trend URLs (comma-separated or new lines). ## `page` (type: `integer`): Starting page number. ## `limit` (type: `integer`): Items per page. ## `maxPages` (type: `integer`): Number of pages to fetch starting from Page. For example page=2 and maxPages=5 fetches pages 2..6. ## `maxItems` (type: `integer`): Maximum number of trend items to push. ## `usersPage` (type: `integer`): Starting page for relevant users of one concrete trend. ## `usersLimit` (type: `integer`): Users per page for one concrete trend rest\_id. ## `usersMaxPages` (type: `integer`): Number of relevant-user pages to fetch starting from Users page. ## `usersMaxItems` (type: `integer`): Maximum number of relevant users to push. ## Actor input object example ```json { "inputTargetType": "discover_trends", "dataMode": "auto", "sort": "latest", "category": "trending", "page": 1, "limit": 10, "maxPages": 1, "maxItems": 10, "usersPage": 1, "usersLimit": 10, "usersMaxPages": 1, "usersMaxItems": 10 } ``` # Actor output Schema ## `results` (type: `string`): No description ## `runReport` (type: `string`): No description ## `userErrorReport` (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 = { "inputTargetType": "discover_trends", "dataMode": "auto", "sort": "latest", "category": "trending", "limit": 10, "maxItems": 10, "usersLimit": 10, "usersMaxItems": 10 }; // Run the Actor and wait for it to finish const run = await client.actor("simoit/x-twitter-preset-trends-scrapper").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 = { "inputTargetType": "discover_trends", "dataMode": "auto", "sort": "latest", "category": "trending", "limit": 10, "maxItems": 10, "usersLimit": 10, "usersMaxItems": 10, } # Run the Actor and wait for it to finish run = client.actor("simoit/x-twitter-preset-trends-scrapper").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 '{ "inputTargetType": "discover_trends", "dataMode": "auto", "sort": "latest", "category": "trending", "limit": 10, "maxItems": 10, "usersLimit": 10, "usersMaxItems": 10 }' | apify call simoit/x-twitter-preset-trends-scrapper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=simoit/x-twitter-preset-trends-scrapper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/acts/ou1WONv5Sg5HG4slT/builds/jE7AvRrOEbKzMF4ld/openapi.json