Twitter Trends API

The Twitter Trends API — the endpoint that returns the list of trending topics for a specific location — has been around so long that the location codes it uses pre-date Twitter itself. WOEID (Yahoo's Where-On-Earth ID system) was built in the 2000s for Yahoo Pipes and never went away. The endpoint built on top of it has been part of the Twitter API since v1.0. Every Twitter dashboard, every brand-monitoring tool, every social-listening product that shows "trending in NYC right now" hits this endpoint.
In 2026 the WOEID system itself is unchanged — Worldwide is still 1, USA is still 23424977, Tokyo is still 1118370. What changed is how access is billed. X no longer sells fixed monthly tiers: the official API, Trends included, is pay-per-usage with no subscriptions ($0.010 per Trends request), needs an X developer account with a saved payment card, and caps pay-per-usage at 3,000,000 Post reads per monthly billing cycle (Enterprise above that, no public price). The endpoint that powered every basic "trending now" widget for fifteen years is now a metered call.
This page covers what "Twitter Trends API" means in 2026: what survived (WOEID, the endpoint shape), what changed (metered billing and the cap), the official endpoint signature, the WOEID reference table you actually need, and a working alternative that doesn't require an X developer account.
Polling 30 cities every 5 minutes = ~259,200 calls/month. On TwitterAPI.io, the top 30 trends per city (count=30, the default) cost about $1,166/month at 15 credits per trend. On official X the same polling costs about $2,592/month at $0.010 per Trends request. About 2.2× less.
What the Trends API Returns
A Trends API call takes a single parameter — a WOEID — and returns the list of currently-trending hashtags and phrases for that location, ranked roughly by velocity. A typical response is 50 trends, each with the topic string, the URL it links to on X, an estimated tweet-volume number (on the official API, when available), and sometimes a context object describing why the trend appears in that location.
The endpoint is read-only and idempotent — call it as often as you like, you get the latest snapshot of the trending list for that WOEID. Trends refresh server-side roughly every 5 minutes; polling more often than that doesn't get you fresher data, only more bills.
Common use cases that have not changed since 2016: real-time content discovery for editorial teams, brand-safety monitoring (is my brand trending unexpectedly?), seed-keyword generation for SEO and ad workflows, sentiment tracking starting points, dashboard widgets for marketing teams. None of those use cases got easier in 2026; the data is just behind a higher wall.
WOEID — The Location System You Need
WOEID stands for Where-On-Earth Identifier, originally Yahoo's geocode system. Twitter adopted it in early v1 and never replaced it — the codes are stable, well-documented, and cover every country, every US state, and most major cities worldwide. WOEIDs are integers, typically 5-8 digits long.
The single most useful WOEID is 1 — Worldwide. Calling the Trends API with woeid=1 returns the trending list across all of X, not filtered to any country or city. Most analytics dashboards start here.
Country and city WOEIDs you'll use most:
The complete list of supported WOEIDs is roughly 500 — every major metro area plus every country. Locations not in the supported set return an empty trends list rather than an error.
Official X Trends API — What It Looks Like in 2026
On the X v2 surface the endpoint is GET /2/trends/by/woeid/{woeid}. The path takes the WOEID as a URL parameter (not query), authorization is a bearer token, and the response is JSON.
Access: an X developer account with a saved payment card. There are no tiers or subscriptions any more — Trends calls are billed pay-per-usage like other resources: X lists Trends at $0.010 per request (docs.x.com/x-api/getting-started/pricing), so polling 30 locations every 5 minutes (259,200 requests a month) costs about $2,592 on the official API. This is the change that brings most teams to this page — pre-2024 the trends endpoint was effectively free; in 2026 every call is metered.
Cap impact: pay-per-usage is capped at 3,000,000 Post reads per monthly billing cycle. A trends call returns trend metadata rather than Posts, but a team polling trends for 20 locations every 5 minutes (288 calls/day × 20 = 5,760 calls/day × 30 days = 172,800 calls/month, about $1,728 at $0.010 each) usually runs search and timeline reads on the same account, and those reads are what push it toward the cap.
Rate limit: like other v2 endpoints, trends has per-endpoint limits in 15-minute windows (see docs.x.com for the current figure). The bottleneck is rarely the per-window rate limit; it's the metered bill and the monthly cap.
Why Most Teams Don't Use the Official Trends API in 2026
The overhead is hard to justify for most use cases smaller than a top-50 newsroom or an enterprise social-listening platform. A small editorial team that wants "trending in 5 cities every 15 minutes" has to open an X developer account, save a payment card and pay $0.010 per call for what is functionally a 50-item JSON response refreshed every 5 minutes server-side.
Three failure modes are common with the official path:
Setup mismatch. A side project, an indie analytics tool, a startup's MVP — all want a trends feed without opening an X developer account, saving a payment card and modelling per-resource billing for a 50-item list.
Polling-cost mismatch. Trends update every 5 minutes server-side. To stay current you poll every 5 minutes per WOEID. For 30 cities that's ~260,000 calls/month — about $2,592 at $0.010 per request, and well under the 3M Post-read cap on its own, but when combined with any other read workload (search, user info, timelines), the cap binds.
Visibility mismatch. The official endpoint returns no historical trend data — only the current snapshot. To track "what was trending yesterday at 3pm in Tokyo" you have to poll continuously and persist the snapshots yourself. That polling cost compounds with every metered call.
TwitterAPI.io Trends Endpoint — Same Shape, No Developer Account
The third-party path most teams move to is TwitterAPI.io's /twitter/trends endpoint. The signature is intentionally similar to the official one — take a WOEID, return the trend list — so existing code that assumed the official shape ports over with a base-URL swap and a one-line change to unwrap each trend.
Endpoint: GET https://api.twitterapi.io/twitter/trends?woeid={woeid}. Auth is X-API-Key header. Required param is woeid. The one optional param is count, the number of trends to return (minimum 30: smaller values are raised to 30; see docs.twitterapi.io).
Pricing: 15 credits ($0.00015) per trend returned, with a 15-credit minimum per request (see twitterapi.io/pricing). count defaults to 30 ($0.0045 a call) and has a floor of 10, so the smallest call returns 10 trends and costs $0.0015. A team polling 30 cities every 5 minutes (~259,200 calls/month) pays about $1,166/month for the top 30 per city. The same workload on the official API costs about $2,592/month at $0.010 per request, however many trends come back.
Same WOEID system: the WOEID values are unchanged across both APIs — Worldwide=1, USA=23424977, Tokyo=1118370. The lookup table above works as-is.
Response shape: a top-level trends list, each item wrapped as {"trend": {...}} with the topic string in name, its position in rank, and the search query the trend resolves to in target.query. There is no tweet-volume field. The nesting differs from the official v2 response, so read item["trend"]["name"] when porting.
When to Use the Official Trends API
Two scenarios where the official path is the right choice:
You already run other workloads on the official API. If your team already has an X developer account billing search or streaming reads, Trends is one more metered call on the same account and the same bill, and the cap math is shared across all your reads.
You need official X branding compliance. Some enterprise data licensing terms require that data come from the official X API surface (compliance with internal data-source policies, contractual obligations to end customers). In those cases TwitterAPI.io is not a substitute regardless of cost.
Outside these two cases, the alternative path costs less per trend poll as long as each call returns fewer than about 66 trends ($0.010 ÷ $0.00015 per trend): about 2.2× less at the default 30 trends. For most teams the answer is "start on the alternative, move up if compliance demands it."
import os
import time
import requests
API_KEY = os.environ["TWITTERAPI_IO_KEY"]
HEADERS = {"X-API-Key": API_KEY}
# Common WOEIDs — see body for the full table
WOEIDS = {
"worldwide": 1,
"usa": 23424977,
"tokyo": 1118370,
"london": 44418,
"sao_paulo": 455825,
"sydney": 1105779,
}
def get_trends(woeid: int) -> list[dict]:
"""Return the current trend list for a WOEID."""
r = requests.get(
"https://api.twitterapi.io/twitter/trends",
params={"woeid": woeid, "count": 30}, # 30 is the minimum; billed per trend returned
headers=HEADERS,
timeout=30,
)
r.raise_for_status()
return r.json().get("trends", [])
# Poll trends for 6 locations every 5 minutes
# Monthly bill: 6 × 288 polls/day × 30 days = 51,840 calls × 30 trends × 15 credits
# = 23,328,000 credits = ~$233.28
for name, woeid in WOEIDS.items():
trends = get_trends(woeid)
print(f"=== {name.upper()} (woeid={woeid}) ===")
for t in trends[:10]:
trend = t["trend"] # each item is wrapped: {"trend": {"name", "rank", "target"}}
print(f" {trend.get('rank')}. {trend['name']}")
# In production wrap the above in a loop with `time.sleep(300)` — trends
# refresh server-side every 5 minutes, polling more often returns the
# same snapshot.
Researching this?Free starter credits cover end-to-end testing — Google sign-in, no card. Get a key.
Questions readers ask
Does Twitter still have a Trends API in 2026?
Yes — GET /2/trends/by/woeid/{woeid} on the official v2 surface, but it is now billed pay-per-usage ($0.010 per request), with no subscriptions or tiers, and needs an X developer account with a saved payment card. The endpoint shape and the WOEID location system are unchanged from earlier API generations; what changed is that every call is metered.
What is a WOEID?
WOEID stands for Where-On-Earth Identifier — Yahoo's geocode system, adopted by Twitter in early v1 and never replaced. Each supported location has a stable integer code: Worldwide is 1, USA is 23424977, Tokyo is 1118370, London is 44418. The system covers every country plus ~500 major metro areas globally. Codes are stable across both the official X API and third-party alternatives.
How often do Twitter trends update?
Server-side roughly every 5 minutes. Polling the endpoint more often than that returns the same snapshot — you get more bills, not fresher data. For most dashboards a 5-minute poll interval is the right cadence; for editorial discovery workflows a 60-second poll catches the trend the moment it cycles.
How much does the Twitter Trends API cost in 2026?
On official X: Trends is billed pay-per-usage at $0.010 per request, with no subscription (docs.x.com/x-api/getting-started/pricing), on an account capped at 3,000,000 Post reads per monthly billing cycle; polling 30 cities every 5 minutes costs about $2,592/month. On TwitterAPI.io: 15 credits ($0.00015) per trend returned, no tier and no cap; the same polling costs about $1,166/month for the top 30 trends per city (count=30, the default).
Can I get historical Twitter trends?
Neither the official Trends API nor most third-party trends endpoints return historical trend snapshots — only the current state. To track "what was trending in Tokyo at 3pm yesterday" you have to poll continuously and persist the snapshots in your own database. A 5-minute poll cadence persisted for one year on 10 WOEIDs is roughly 10.5M rows; manageable on PostgreSQL or any time-series store.
Why do some trends show no tweet_volume?
Tweet volume is estimated server-side and only attached to trends above a confidence threshold. Newer or smaller trends typically come through with tweet_volume: null — the trend is real, the volume estimate hasn't accumulated enough signal yet. That applies to responses that carry a volume at all. TwitterAPI.io's /twitter/trends returns no volume field: each trend has name, rank and target.query, so count matching tweets yourself with /twitter/tweet/advanced_search if you need a number.
Can I get trends for a city not in the WOEID list?
No — the trends system only computes per-location trends for the ~500 WOEIDs in the supported set. Locations outside the set return an empty trends list rather than an error. Smaller cities are aggregated into their containing metro or country WOEID. For a city not in the list, the nearest containing region (usually the country) is the closest approximation available.
Continue
- /
- /blog/twitter-api-pricing-2025
- /blog/twitter-trends
- /blog/twitter-api-trending
- /blog/twitter-search-api-complete-guide-2025
- /pricing
- 01How to Block Words on Twitter (X): Muted Words, Step by Step
- 02Twitter (X) Drafts: How to Find, Access and Keep Them
- 03Twitter (X) API in AutoGen: a Search Tool and a Two-Agent Team on Real X Data
- 04Twitter (X) API in PHP: a Guzzle client with safe decoding and cursor paging
- 05Twitter (X) Account Suspended: Why It Happened and How to Get It Back
- 06Twitter (X) Trends API — A Developer's Tutorial
- 07Twitter (X) Trends API in Python — Three Paths, One Tutorial
- 08Twitter Trends — Find, Track, Automate
Writing about something you built with TwitterAPI.io? Our community rewards program pays API credits for honest tutorials, build logs and videos.
Stop reading. Start building.
Starter credits cover real testing on real data. Google sign-in, no card, no application queue.
Get an API keyAlready building with TwitterAPI.io? Publish an honest tutorial or build log about it and earn up to $200 a month in API credits.