What is the X Trends API?

X Trends API is a programmatic interface for collecting current public X trend snapshots by numeric WOEID.

What do I submit in woeids?

Submit one or more known location identifiers as numeric strings. The endpoint does not translate a city or country name into a WOEID.

How does results_limit work?

It defaults to 100, accepts integers from 20 through 2,000, and is applied separately to each WOEID. The source may expose fewer current trends than the requested cap.

What does each trend record contain?

A record contains the trend name as id and text, an upstream rank when present, collected_at, and extra fields for the WOEID, query, and description when available.

Does this endpoint return historical trends?

No. It returns a current snapshot from each requested WOEID; create a history by scheduling and storing repeated runs in your own system.

Why might one trend appear for only one submitted WOEID?

Saved records deduplicate by normalized trend name within a task. If the same name occurs in several submitted locations, the first saved record can retain only one extra.woeid value.

How is the X Trends API priced?

Each successfully saved normalized trend costs 0.5 SocQ credits. The estimate uses results_limit for every submitted WOEID, and unused precharged credits are refunded after the task settles.

X Trends API: Current Trends by WOEID

X Trends

X trends are a location-keyed snapshot of public topics available for a numeric WOEID, with the source name, rank, query, description, and collection time kept together. This structure supports regional topic discovery and repeated observation while making clear that each record reflects collection time rather than a historical trend series.

Features

Location-keyed collectionRequest current public trends for one or more known numeric WOEIDs and retain the originating identifier in extra.woeid.
Source ranking preservedKeep the upstream rank in metrics.rank when it is available without replacing it with a SocQ-calculated score.
Useful trend contextReceive the trend name with an upstream query and provider description when those fields are exposed.
Independent caps per locationApply results_limit separately to every submitted WOEID while collecting each location's currently available trend set once.

Parameters

Parameters	Required	Description
`woeids`	Required	Required array of one or more known X location identifiers, each represented as a non-empty numeric string.
`results_limit`	Optional	Optional integer cap applied separately to each WOEID. Defaults to 100 and accepts values from 20 through 2,000.

How to Use

Start with numeric WOEIDs you already know, choose a per-location cap, and treat the returned records as a collection-time snapshot.

Enter one or more known WOEIDs as numeric strings; this endpoint does not resolve place names.
Choose an integer results_limit from 20 to 2,000, or keep the default of 100 per WOEID.
POST the request to /v1/x/trends, then poll /v1/tasks/{task_id} until the task succeeds.
Read data.results.items and follow the task result next_cursor while has_more is true.

curl -X POST "https://api.socq.ai/v1/x/trends" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"woeids":["1"],"results_limit":100}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is true

Best Use Cases

Watch topics in a known market: Collect the current names, ranks, and descriptions associated with a location identifier your monitoring system already maintains.
Build recurring observation snapshots: Run the same WOEID on a schedule you control and store collected_at with every result for later change analysis.
Create a topic-review queue: Use the returned name, query, rank, and description to prioritize public topics for analyst review or a downstream discovery workflow.

Pro Tips

Prepare numeric WOEIDs before submitting a task; place names and free-text locations are not accepted.
The provided default 1 follows the backend's published request example; replace it with the identifier that matches your intended scope.
Treat results_limit as a per-WOEID ceiling because a current trend set can contain fewer rows than requested.
Run overlapping locations in separate tasks when retaining every trend-to-location association matters, because identical trend names can deduplicate within one task.
Use collected_at as the observation time; created_at is null because the source does not expose a trend creation timestamp.
Task result cursors page already saved records and do not request another page of trends from the provider.

Use these APIs when you need a different type of public X data.

Twitter Tweet Scraper API — Retrieve public post text, authors, engagement, media, hashtags, mentions, and conversation relationships from x.com or twitter.com status URLs.
Twitter Profile Scraper API — Retrieve public account identity, biographies, avatars, cover images, account status, and visible audience statistics by username.
Twitter User Tweets Scraper API — Collect recent public posts, authors, media, hashtags, mentions, and engagement by username with replies excluded.
Twitter Search API — Find public posts by search expression with latest or top ordering and a configurable result limit.
X Followers List API — Collect public follower account identities and visible profile metrics for one or more X usernames.
X Following List API — Collect profiles followed by public X accounts, including identity, biographies, account signals, visible counters, and source usernames.
X Post Quotes API — Collect public quote posts for known status URLs with commentary, authors, engagement, media, timestamps, and source-post context.
X Post Replies API — Collect public replies from X post URLs with selectable ordering, reply text, authors, visible engagement, media, and parent-post context.
X Post Retweeters API — Collect a task-level unique set of normalized public profiles for accounts that reposted known X or Twitter status URLs.

Combine X data with public data from other supported social platforms.