# X (Twitter) Trends Scraper (`labrat011/x-trends-scraper`) Actor
Get what is trending on X (Twitter) right now in any country or city, with how long each trend has been trending, its best rank in the last 24 hours, and where else it trends. Optional full hourly history for the last 24 hours. No X account or API key.
- **URL**: https://apify.com/labrat011/x-trends-scraper.md
- **Developed by:** [mick\_](https://apify.com/labrat011) (community)
- **Categories:** Social media, News
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet
## Pricing
from $0.10 / 1,000 trends
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/actors/running/actors-in-store.md#pay-per-event
## What's an Apify Actor?
An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.
Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.
## 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.
Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.
For examples already wired to this Actor's own input schema, see the [API](#api) section below.
Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).
# README
## X (Twitter) Trends Scraper
See what is trending on X (Twitter) in any country or city, and **how long each trend has been trending**. Every row carries its best rank in the last 24 hours, hours on the list, when it first appeared, and where else it is trending. No X account, no API key.
| At a glance | |
|---|---|
| **You give it** | Locations: worldwide, countries or cities |
| **You get** | One row per trend: rank, best rank in 24 hours, hours trending, first seen, where else it trends |
| **Price** | $0.0026 per run + $0.0002 per trend (Free plan, lower on paid plans) |
| **Speed** | Five countries in about 7 seconds |
| **Needs** | Nothing: no login, no API key, no proxy |
### What you get
- **Current trends** for worldwide, 60+ countries, and cities (`New York, US`, `united-kingdom/london`), up to 50 per location.
- **Recent history on every trend:** `hoursTrending24h`, `bestRank24h`, `firstSeenAt`, and `isNew` for topics that just broke onto the list, from the last 24 hourly snapshots (about 20 hours). Spot what is rising versus what has been there all day.
- **Cross-location overlap:** `locationCount`, `locationsTrendingIn`, `bestRankAcrossLocations` across all locations in the run.
- **Full hourly history** (optional): every hourly snapshot the source keeps (about the last 20 hours), about 1,100 rows per location.
- **Fast and light:** five countries took 7 seconds; 100 trends used $0.0007 of platform usage.
**Freshness:** trends come from snapshots of X's trending list taken about every 52 minutes, so the current list can be up to about an hour old. The source keeps the last 24 snapshots, so history fields cover roughly the last 18 to 20 hours, not a full 24. In a side-by-side test against a live X source, 42 to 44 of the 50 trends matched; the rest had rotated since the last snapshot.
### Use cases
- **Newsjacking and social media marketing.** Catch a trend in its first hour (`isNew`) and post while it is rising.
- **Brand safety.** Know what is trending before a campaign goes out.
- **Media and research dashboards.** Hourly trend history by country, for charts and reports.
- **Cross-market comparison.** Which topics trend in the US and the UK at once, and which are local.
- **Alerts.** Tell me when a keyword or hashtag starts trending anywhere.
### Example inputs
#### Trends right now
```json
{ "locations": ["worldwide", "US", "UK", "India"] }
```
#### Cities
```json
{ "locations": ["New York, US", "Los Angeles, US", "united-kingdom/london"], "maxTrendsPerLocation": 20 }
```
#### Full hourly history for one country
```json
{ "locations": ["US"], "includeHistory": true }
```
### Input
| Field | What it does |
|---|---|
| `locations` | `worldwide`, a country code (`US`, `UK`, `JP`...), a country name, `City, Country`, or `country/city`. |
| `maxTrendsPerLocation` | 1 to 50. Default 50. |
| `includeHistory` | Every hourly snapshot the source keeps (up to 24, about the last 20 hours) instead of just the current list. |
### Output
A real row from a test run on 2026-09-26:
```json
{
"rank": 1,
"name": "#YouManiacSeriesEP5",
"isHashtag": true,
"searchUrl": "https://x.com/search?q=%23YouManiacSeriesEP5",
"location": "worldwide",
"locationSlug": "worldwide",
"snapshotAt": "2026-09-26T16:03:20Z",
"bestRank24h": 1,
"hoursTrending24h": 7,
"firstSeenAt": "2026-09-26T10:51:34Z",
"isNew": false,
"locationCount": 2,
"locationsTrendingIn": [
"worldwide",
"US"
],
"bestRankAcrossLocations": 1
}
```
With `includeHistory` on, each row is one trend in one hourly snapshot: `rank`, `name`, `isHashtag`, `searchUrl`, `location`, `locationSlug`, `snapshotAt`. The history and cross-location fields are left out, because they describe the current list only.
Field meanings:
- `hoursTrending24h`: number of hourly snapshots (out of up to 24) the trend appears in.
- `bestRank24h` and `firstSeenAt`: best rank and first appearance within those snapshots.
- `isNew`: the trend is only in the newest snapshot.
- `locationCount`, `locationsTrendingIn`, `bestRankAcrossLocations`: across the locations in this run only.
### Pricing
Pay per event:
- **$0.0026** per run start
- **$0.0002** per trend row on the Free plan (lower on higher Apify plans)
Apify platform usage is billed separately to your account and is tiny: 100 trends used $0.0007.
| What you scrape | Actor cost |
|---|---|
| Worldwide + US (100 trends) | about $0.023 |
| 10 countries (500 trends) | about $0.10 |
| 1 country, full history (about 1,100 rows) | about $0.22 |
### Automate it with n8n
Each workflow uses n8n's official **Apify** node, operation **Run actor and get dataset**, actor `labrat011/x-trends-scraper`. Paste the input into **Input JSON**.
#### 1. New trend alert to Slack (hourly)
```
Schedule Trigger (every hour)
> Apify: Run actor and get dataset { "locations": ["US"], "maxTrendsPerLocation": 20 }
> Filter: isNew is true
> Slack: "New on X in the US at #{{ $json.rank }}: {{ $json.name }} {{ $json.searchUrl }}"
```
#### 2. Keyword watch across countries
```
Schedule Trigger (every hour)
> Apify: Run actor and get dataset { "locations": ["worldwide", "US", "UK", "CA", "AU", "IN"] }
> Filter: name contains "yourbrand" (case-insensitive)
> Email / SMS: "Trending in {{ $json.locationsTrendingIn.join(', ') }}"
```
#### 3. Trend history dashboard
```
Schedule Trigger (every 12 hours)
> Apify: Run actor and get dataset { "locations": ["US", "UK"], "includeHistory": true }
> Google Sheets / BigQuery: append rows, skipping ones already stored (key: location + snapshotAt + rank)
> Looker Studio: chart rank over time per topic
```
#### 4. AI content ideas from trends
```
Schedule Trigger (twice a day)
> Apify: Run actor and get dataset { "locations": ["US"], "maxTrendsPerLocation": 30 }
> Filter: hoursTrending24h <= 3 (fresh topics only)
> OpenAI / Anthropic: "Which of these fit our brand (describe it)? Suggest a post for each."
> Notion: save the ideas for the social team
```
#### 5. Global vs local topics report
```
Schedule Trigger (weekly)
> Apify: Run actor and get dataset (10 countries)
> Filter: locationCount >= 3
> Google Docs: "Topics trending in 3+ countries this week"
```
### For AI agents
- **Actor:** `labrat011/x-trends-scraper`
- **Smallest input:** `{ "locations": ["worldwide"] }`
- **One row = one trend in one location at the snapshot time.** Key fields: `rank`, `name`, `location`, `snapshotAt`, `bestRank24h`, `hoursTrending24h`, `locationsTrendingIn`.
- **Billing:** `apify-actor-start` once per run, `trend` per row. Cap spend with `maxTrendsPerLocation` or a maximum cost per run.
- **Run it:** `POST https://api.apify.com/v2/acts/labrat011~x-trends-scraper/run-sync-get-dataset-items` with the input as the JSON body, or call it from the Apify MCP server.
- **Done signal:** the run's status message reads `Saved N trends from L locations in R requests.` Locations with no data are listed after `No data for:`. If no location has data, the run fails instead of returning an empty dataset.
### FAQ
**Why is tweet volume not included?** X stopped showing reliable tweet counts on its public trends. Rather than return empty columns, this actor gives you rank history and spread across locations instead.
**How fresh is the data?** Trends refresh about hourly. `snapshotAt` on every row says exactly when the list was taken.
**Why is it called 24h if it covers about 20 hours?** The source keeps the last 24 snapshots, taken about every 52 minutes. The field names count snapshots; the time they span is about 18 to 20 hours. Repeat snapshots taken seconds apart are dropped so they do not inflate the counts.
**Which cities are supported?** Most large cities X tracks. Use `City, Country` (`Chicago, US`) or the path form (`united-states/chicago`). A location with no data is named in the run log and the status message, and is not charged. A few countries (for example Bangladesh) are not covered by the source.
### Support
Open an issue on the actor's Issues tab with the run ID and it will be looked at.
# Changelog
This Actor's version history is a separate document: https://apify.com/labrat011/x-trends-scraper/changelog.md
# Actor input Schema
## `locations` (type: `array`):
worldwide, a country code (US, UK, IN, JP, BR...), a country name (South Africa), or a city as City, Country (New York, US) or country/city (united-kingdom/london).
## `maxTrendsPerLocation` (type: `integer`):
Up to 50, X's own list length.
## `includeHistory` (type: `boolean`):
Every hourly snapshot the source keeps (up to 24, about the last 20 hours) instead of just the current list. About 20 times more rows. Rows have rank, name, location and snapshotAt only.
## `proxyConfiguration` (type: `object`):
Not needed normally.
## Actor input object example
```json
{
"locations": [
"worldwide",
"US",
"UK"
],
"maxTrendsPerLocation": 20,
"includeHistory": false,
"proxyConfiguration": {
"useApifyProxy": false
}
}
```
# Actor output Schema
## `trends` (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 = {
"locations": [
"worldwide",
"US",
"UK"
],
"maxTrendsPerLocation": 20
};
// Run the Actor and wait for it to finish
const run = await client.actor("labrat011/x-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",
"US",
"UK",
],
"maxTrendsPerLocation": 20,
}
# Run the Actor and wait for it to finish
run = client.actor("labrat011/x-trends-scraper").call(run_input=run_input)
# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).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",
"US",
"UK"
],
"maxTrendsPerLocation": 20
}' |
apify call labrat011/x-trends-scraper --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"type": "http",
"url": "https://mcp.apify.com/?tools=fetch-actor-details,labrat011/x-trends-scraper"
}
}
}
```
The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).
## OpenAPI specification
Download the OpenAPI definition: https://api.apify.com/v2/actors/12EMMKcchu17O4htU/builds/R8MnrHA1O89FdltZf/openapi.json