# X (Twitter) Trends Scraper by Country & City (`arjun_code/x-twitter-trends-scraper`) Actor

Discover current X (Twitter) trends worldwide, by country, or by city. Export up to 50 ranked topics per location with search links and X snapshot times for regional research, content planning, and scheduled reports. No X login, API key, or proxy setup required.

- **URL**: https://apify.com/arjun\_code/x-twitter-trends-scraper.md
- **Developed by:** [Arjun AI](https://apify.com/arjun_code) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 location trend snapshots

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/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

Find **current X (Twitter) trending topics and hashtags** by country, city, or worldwide. Choose locations from the dropdowns and get one Dataset row per topic, including its rank, X search link, and the time X generated the trend list. No X login, API key, cookies, or proxy setup is required.

Compare regions, find timely ideas for local reporting or content planning, and schedule repeat runs to build your own trend history. This Actor collects current snapshots; it does not retrieve past trends or posts behind a topic.

### What you get

- Up to 50 ranked topics for each selected location, with separate country and city lists.
- A direct X search link and source snapshot time for every topic.
- Exportable Dataset rows for spreadsheets, dashboards, API workflows, or scheduled reports.

X supplies post volume only when available. The Actor leaves missing counts as `null` rather than inventing an estimate.

### How to use

1. Select one or more countries, cities, or both from the dropdowns. Leave both empty to get Worldwide trends.
2. Keep the default maximum of 50 topics per location, or lower it if you need fewer rows.
3. Run the Actor and open its Dataset. Export the results in the format you need or use them through the Apify API.

The country and city selectors are independent: choosing the United States does not automatically choose New York. Each selected location has its own list and up to 50 results. The Actor checks X's current location list when it runs; a location that X no longer supports may return no data.

### Input example

The form and API input both use readable location names. City names include their country to distinguish places with the same name:

```json
{
  "countries": ["United States (US)"],
  "cities": ["New York — United States (US)"],
  "maxTrendsPerLocation": 50
}
```

This example selects the United States and New York. With the default maximum, it can produce up to 100 Dataset rows.

### Output example

Each row represents one trend at one location. This example is based on a real X response; topic names and positions change over time.

```json
{
  "location_name": "United States",
  "location_woeid": 23424977,
  "location_type": "Country",
  "country_code": "US",
  "position": 1,
  "trend_name": "#ADifferentWorld",
  "trend_url": "http://twitter.com/search?q=%23ADifferentWorld",
  "trend_query": "%23ADifferentWorld",
  "tweet_volume": null,
  "as_of": "2026-09-24T08:51:56Z"
}
```

`position` is derived from X's result order, not supplied as a separate X field. `as_of` is when X generated that location's trend list (UTC), not the time when an individual topic first appeared. X does not always provide `tweet_volume`; a `null` value means no count was supplied, not zero posts. The Actor does not estimate missing counts.

### Pricing

Billing is **per successful location, not per topic row**. One location with results triggers one `trend-location-snapshot` event, whether it returns 5 or 50 topics. The current price is $0.0015 per location on Free/Bronze, $0.0012 on Silver, and $0.0010 on Gold or higher. At the default 512 MB memory, a separate $0.00005 Actor-start event applies per run. For example, the United States and New York together incur $0.00305 in event charges on Free/Bronze when both return trends. Empty or failed locations do not trigger a snapshot event, but the start event still applies. Check the Pricing tab for current rates and whether platform usage is billed separately before a large run.

### Freshness and limitations

Each run returns a current X snapshot. There is no past-date input. To build a history, schedule regular runs on Apify and retain their Datasets. `as_of` is X's snapshot time in UTC, not the moment an individual topic first appeared. Topic names, positions, and available locations can change between runs.

If one location cannot be fetched, the Actor continues with the others and records the problem in the run's `FAILURES` key-value record. The run fails if every selected location fails.

### FAQ and support

#### Why is `tweet_volume` null?

X did not provide a count for that trend. `null` does not mean zero posts.

#### Can I get trends from a previous date?

No. This Actor only fetches the current list. Schedule it to collect future snapshots over time.

#### Does this Actor collect the posts behind each trend?

No. It returns trend names and X search links, not the matching posts. For help with a failed run, include the run ID in the Actor's Issues tab; do not post account credentials.

### Related X tools

For account research, try [X People Search](https://apify.com/arjun_code/x-twitter-people-search-scraper). For the details and media of a known post URL, use [X Media Downloader](https://apify.com/arjun_code/x-twitter-media-downloader).

# Actor input Schema

## `countries` (type: `array`):

Select one or more countries, or Worldwide. You can also select cities below. If both fields are empty, Worldwide is collected.

## `cities` (type: `array`):

Select one or more cities. Each option includes its country to distinguish cities with the same name. Country and city selections are independent.

## `maxTrendsPerLocation` (type: `integer`):

Save up to this many trending topics for each location. X currently returns at most 50 topics per location.

## Actor input object example

```json
{
  "countries": [],
  "cities": [],
  "maxTrendsPerLocation": 50
}
```

# Actor output Schema

## `results` (type: `string`):

One Dataset item per trend and location.

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("arjun_code/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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("arjun_code/x-twitter-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 '{}' |
apify call arjun_code/x-twitter-trends-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,arjun_code/x-twitter-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 <APIFY_API_TOKEN>` 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/BXXafPoMbI02xuhoy/builds/T6w18H2y3nEGYjqwU/openapi.json