--- title: "Trends" method: GET path: "/trends" tags: ["Trends"] --- # Trends `GET /trends` ## Request - Base URL: `https://api.twitterapis.com/twitter` - URL: `https://api.twitterapis.com/twitter/trends` - Auth: HTTP bearer Fetch the current top trends for one location. Ask for it by country name, ISO code, or numeric WOEID; with no location parameter you get Worldwide. X returns roughly 50 trends per location, ranked. Pass category instead: trending, news, sports, entertainment or for_you reads that X Explore tab, and business_and_finance keeps only the ranked trends X labels Business and finance on its Trending and News tabs. Cost: $0.0008 per call. ## Query parameters - `country` string: Country name or ISO code, e.g. "US" or "Japan". Resolved against the trends locations list, country-level entries only. - `woeid` integer: Numeric WOEID from /twitter/trends/locations. Takes precedence over country when both are sent. - `category` string: Read a category instead of a location. trending, news, sports, entertainment and for_you each read that X Explore tab. business_and_finance is not a tab but a filter: it reads the Trending and News tabs and keeps only the ranked trends X labels "Business and finance", with no story items. Case-insensitive. Results reflect the Explore view of the X account the API reads with, not yours. Cannot be combined with country or woeid (400 bad_request). An unknown value returns 400 bad_request, and the message lists the six values. - `count` integer: Truncate the returned list to this many trends. X has no count of its own; it always returns its full set (about 50 for a location). - `fields` string - `compact` '1' ## Response `200` Read the current trending topics for a location, an Explore tab or a trend label. - object - `category` string: The category you asked for, lowercased: trending, news, sports, entertainment, for_you or business_and_finance. Present only when the call sent category; a location call has no category key. - `location` TrendServedLocation: The location a trends response was actually served for, echoed back in the trends envelope so the caller knows which place the trends belong to. - `name` string: Human-readable location name, for example "Worldwide" or "United States". - `woeid` integer: The Yahoo! Where On Earth ID for the location; pass it back as the woeid parameter to re-request the same place. - `as_of` string: ISO 8601 timestamp of when X computed this trend list. - `created_at` string, nullable: ISO 8601 timestamp X reports for the trend window. Null on a category call, where X reports no trend window. - `count` integer: Number of trends in this response, after any count truncation. - `trends` Trend[]: Ranked trend objects: name, url, query, promoted_content, tweet_volume, is_hashtag, rank, meta_description. On a category call each also carries is_ai_story. On an Explore tab story items follow the ranked trends; business_and_finance returns ranked trends only, re-ranked from 1. - `name` string: The trend text, for example a hashtag or phrase. On a story item from a category call, the headline. - `url` string: x.com search URL for the trend. On a story item from a category call, the story page under https://x.com/i/trending/ followed by the story id. - `query` string: Search query for the trend. URL-encoded on location trends; on a story item from a category call, the headline. - `promoted_content` unknown - `tweet_volume` integer, nullable: Approximate number of tweets in the trend over the trailing window; null when X does not report a volume. On a story item from a category call, the post count read from X's line, for example 116000 from "116K posts". - `is_hashtag` boolean: Whether the trend is a hashtag (its name starts with #). Derived from the trend name when X sends no literal flag. - `rank` integer: 1-based position of the trend in X's trending-rank order, assigned before any count truncation. On an Explore tab category call, story items are ranked after the ranked trends. On category=business_and_finance the kept trends are re-ranked from 1 after the label filter. - `meta_description` string, nullable: The context line X shows under a trend. On a category call it is X's own line, for example "Music · Trending" on a ranked trend or "8 hours ago · News · 116K posts" on a story item. category=business_and_finance keeps only the ranked trends whose line starts with "Business and finance", for example "Business and finance · Trending". Null on every location trend today: those are read from X's REST trends/place.json, whose trend object carries no context string, so there is nothing to return; the field fills in on its own the day that changes. It is deliberately not synthesised from tweet_volume, because a line written here and presented as X's would be a fabrication. - `is_ai_story` boolean: Present only on a category call. True on an item X itself marks as AI-written: every story item from an Explore tab's stories module, and any ranked trend X flags as AI-written (which keeps its rank). False on the other ranked trends. category=business_and_finance returns ranked trends only, never story items. Location trends do not carry this key. ## Other responses - `400`: Bad request - `401`: Unauthorized - `402`: Insufficient credits - `403`: Forbidden - `404`: Not found - `429`: Rate limited - `5XX`: Server error --- [API](https://skmtc.dev/twitterapis/apis/twitterapis-api.md) · [All operations](https://skmtc.dev/twitterapis/apis/twitterapis-api/llms.txt) · [OpenAPI document](https://skmtc.dev/twitterapis/apis/twitterapis-api/revisions/a33ce0fedb3c?raw)