Timeline & DMs
Twitter trends API by region, WOEID & search
Get Twitter and X trends by WOEID region. Return ranked topics, hashtags, search queries, descriptions, tweet volume, and result counts. See examples.
- 200
- 401
- 402
- 424
- 429
- 502
GET
Twitter trends API by region, WOEID & search
GET /x/trends to retrieve ranked regional topics.
This Twitter trends API supports planning, monitor seeding, search jobs, and alerts.
Each example emits one JSON record for every returned trend.
Store trend_name for every result.
Preserve rank, description, and query when the response includes them.
Leave omitted fields unset. Use the trend name when query is missing.
Also store region_woeid, returned_count, and your own detected_at timestamp.
Pass search_query to Search Tweets for matching tweets.
A Twitter API trending workflow should preserve each snapshot before searching.
Build a regional trend monitor
Poll one WOEID on a consistent schedule. Store every trend name and returned optional field. Keep missing values unset. PreservetweetVolume as null when X returns null.
Compare ranks within the same region. Do not mix worldwide and country results
inside one ranking. Keep the WOEID on every row.
Use the returned search query to retrieve matching tweets. Preserve the trend
snapshot before starting that search. This links each tweet batch to the
regional topic that triggered it.
Treat missing tweet volume as unknown. Do not convert it to zero. X may omit
that field for some trends.
Query parameters
integer
Positive Where On Earth ID for the region. Invalid or nonpositive values fall back to
1 (worldwide). See Trends guide for common regions.integer
Number of trends to return. Default
30, max 50. Invalid or below-minimum values fall back to 30.Headers
string
Send a full Xquik account API key.
string
Bearer xq_your_guest_key_here authenticates paid_reads guest keys through the API-key scheme’s Bearer alias. Direct MPP uses the Payment ... credential from the WWW-Authenticate: Payment challenge.Response
200 OK
object[]
Array of trending topics.
Trend object fields.
string
Trend name or hashtag.
number
Trend rank. Omitted if unavailable.
string
Trend description. Omitted if unavailable.
string
Search query for this trend. Omitted if unavailable.
string | null
Promotion identifier. Null for organic trends.
number | null
Approximate public post volume when X supplies it.
string
X search URL for the trend.
number
Number of trends returned.
number
WOEID used for the request.
401 Unauthenticated
402 Payment required
Account keys receive account payment options. Guest keys receive only the guest top-up action. Anonymous calls receiveWWW-Authenticate: Payment plus a guest wallet action.
Failed requests never create checkout. Confirm a payment option first.
502 X API unavailable
429 Rate limit exceeded
Retry-After when present. Otherwise, use the JSON retryAfter field.
424 Dependency failed
xquik-api-contract: 2026-04-29 to opt in. Default v1 returns 502.
Twitter trends API questions
How do I get Twitter trends programmatically?
CallGET /x/trends with a regional woeid and a result count.
Read each trend’s name, rank, query, description, and available tweet volume.
Can I track trending hashtags by region?
Yes. Poll the same WOEID on a stable schedule. Compare ranks within the same region. Save each detection time. Usequery to search tweets related to each trending hashtag.
Use the trend name when the response omits query.
How do I authenticate to the Twitter trends API?
Send an Xquik API key or OAuth bearer token. Apaid_reads guest key can use the API-key scheme’s Bearer alias.
For direct MPP, anonymous requests get a payment challenge.
How much does a trends request cost?
The pricing callout above shows the current credit and direct MPP cost. Failed requests return a documented error without creating checkout.How do I build trend tracking into an app?
Schedule one regional request, then store each returned snapshot. Compare the latest ranks with the previous snapshot. Send meaningful changes to a dashboard, monitor, or alert queue.Does this replace X’s official API?
No. This page documents Xquik, an independent third-party service. It does not document X’s official API.This endpoint returns trends directly from X. For broader Radar topic discovery, use List Radar Items.
Next steps. Search Tweets to find tweets about a trending topic.
- 200
- 401
- 402
- 424
- 429
- 502
Twitter trends API by region, WOEID & search