# X (Twitter) Trends API Reference Canonical: https://monsterapi.co/docs/api/x-twitter-trends Read the X (Twitter) Trends reference. Review parameters, response fields, examples, and current credit prices. OpenAPI specification: [X (Twitter)](https://monsterapi.co/docs/openapi/platforms/twitter.yaml). --- Current operation prices: [public catalog](https://monsterapi.co/account/api/v1/public/api-prices). Prices use credits per request. --- # X (Twitter): Trending topics by place `GET /twitter/api/trends` Documentation: https://monsterapi.co/docs/api/twitter#trending-topics-by-place Operation ID: `twitter_trends` Returns trending topics for one place, including promoted topics, the place and the time of the list. Reports worldwide trends when woeid is omitted. ## Authentication Send your billing API key in the `Authorization: Bearer ` header. Your account login is separate. ## Inputs - `woeid` (query, optional): Optional geographic identifier from `places[].woeid` in [GET /trends/locations](https://monsterapi.co/docs/twitter#trends-and-topics). Decimal digits from 1 to 4294967295, no leading zero; default 1 for worldwide trends. ## Responses - 200: Trends of the place - 400: Identifier outside the accepted set Refused at the gateway: the request target, path and query string together, is longer than 8,192 bytes; or the headers, the target counted among them, exceed 16,384 bytes or 64 fields - 401: #/components/responses/GatewayUnauthorized - 402: #/components/responses/GatewayPaymentRequired - 403: #/components/responses/GatewayForbidden - 404: No such place - 405: `method_not_allowed`: the endpoint answers GET alone, and any other method, HEAD included, is refused Refused at the gateway: the path exists, but no operation on it takes the method of the request, HEAD included; `Allow` names the methods that do - 409: #/components/responses/GatewayConflict - 429: #/components/responses/GatewayTooManyRequests - 500: The requested information could not be read; this does not establish that the object is absent - 501: The requested information is unavailable without sign-in - 503: Rate limit (`rate_limited`), temporary request failure (`upstream_error`), service capacity unavailable (`no_proxies`), too many concurrent requests (`overloaded`), or request temporarily unavailable (`upstream_stale`) Refused at the gateway: the check could not complete, the account is suspended, or the platform did not answer; each may pass later, and `Retry-After` comes only when the platform did not answer ## Credits Check the live price in the documentation before sending. Platform 2xx and 4xx responses can use credits, including empty data. Gateway refusals and 5xx responses do not use credits. Each pagination request is a separate call. https://monsterapi.co/docs/pricing ## Request template Replace path placeholders and add the required query parameters from the Inputs section before sending. ```shell curl --get 'https://api.monsterapi.co/twitter/api/trends' \ -H 'Authorization: Bearer ' ``` --- # X (Twitter): Trend locations `GET /twitter/api/trends/locations` Documentation: https://monsterapi.co/docs/api/twitter#trend-locations Operation ID: `twitter_trend_locations` Returns places with reported trends and their geographic identifiers. ## Authentication Send your billing API key in the `Authorization: Bearer ` header. Your account login is separate. ## Inputs ## Responses - 200: Places that have trends - 400: #/components/responses/GatewayBadRequest - 401: #/components/responses/GatewayUnauthorized - 402: #/components/responses/GatewayPaymentRequired - 403: #/components/responses/GatewayForbidden - 404: X answered that the list of places is not there - 405: `method_not_allowed`: the endpoint answers GET alone, and any other method, HEAD included, is refused Refused at the gateway: the path exists, but no operation on it takes the method of the request, HEAD included; `Allow` names the methods that do - 409: #/components/responses/GatewayConflict - 429: #/components/responses/GatewayTooManyRequests - 500: The requested information could not be read; this does not establish that the object is absent - 501: The requested information is unavailable without sign-in - 503: Rate limit (`rate_limited`), temporary request failure (`upstream_error`), service capacity unavailable (`no_proxies`), too many concurrent requests (`overloaded`), or request temporarily unavailable (`upstream_stale`) Refused at the gateway: the check could not complete, the account is suspended, or the platform did not answer; each may pass later, and `Retry-After` comes only when the platform did not answer ## Credits Check the live price in the documentation before sending. Platform 2xx and 4xx responses can use credits, including empty data. Gateway refusals and 5xx responses do not use credits. Each pagination request is a separate call. https://monsterapi.co/docs/pricing ## Request template Replace path placeholders and add the required query parameters from the Inputs section before sending. ```shell curl --get 'https://api.monsterapi.co/twitter/api/trends/locations' \ -H 'Authorization: Bearer ' ``` --- # X (Twitter): Popular topic posts `GET /twitter/api/trends/timeline` Documentation: https://monsterapi.co/docs/api/twitter#popular-topic-posts Operation ID: `twitter_trend_timeline` Returns a preview of popular posts for a topic tag. Has no search modes or limit parameter; continuation is available only when next_cursor is present. ## Authentication Send your billing API key in the `Authorization: Bearer ` header. Your account login is separate. ## Inputs - `tag` (query, required): Required topic as written, 1 to 256 printable Unicode characters, not only spaces; excludes controls, invisible formatting characters and line or paragraph separators. URL-encode the query value, for example tag=%23bitcoin or tag=New%20York - `cursor` (query, optional): Optional continuation: send top-level `next_cursor` from [GET /trends/timeline](https://monsterapi.co/docs/twitter#trends-and-topics) unchanged as `cursor` to GET /trends/timeline. Up to 8,192 characters; base64/base64url decoding to at least five bytes, or two signed 64-bit decimal numbers separated by |. Omit for the first page. ## Responses - 200: Guest preview; next_cursor is present only when X gave one - 400: Tag or cursor outside the accepted set, or a cursor that cannot continue this list Refused at the gateway: the request target, path and query string together, is longer than 8,192 bytes; or the headers, the target counted among them, exceed 16,384 bytes or 64 fields - 401: #/components/responses/GatewayUnauthorized - 402: #/components/responses/GatewayPaymentRequired - 403: X answered with the error of a suspended account Refused at the gateway: the API key is unknown or revoked - 405: `method_not_allowed`: the endpoint answers GET alone, and any other method, HEAD included, is refused Refused at the gateway: the path exists, but no operation on it takes the method of the request, HEAD included; `Allow` names the methods that do - 409: #/components/responses/GatewayConflict - 429: #/components/responses/GatewayTooManyRequests - 500: The topic preview is unreadable or empty without next_cursor; this does not establish that the topic is absent - 501: The requested information is unavailable without sign-in - 503: Rate limit (`rate_limited`), temporary request failure (`upstream_error`), service capacity unavailable (`no_proxies`), too many concurrent requests (`overloaded`), or request temporarily unavailable (`upstream_stale`) Refused at the gateway: the check could not complete, the account is suspended, or the platform did not answer; each may pass later, and `Retry-After` comes only when the platform did not answer ## Credits Check the live price in the documentation before sending. Platform 2xx and 4xx responses can use credits, including empty data. Gateway refusals and 5xx responses do not use credits. Each pagination request is a separate call. https://monsterapi.co/docs/pricing ## Request template Replace path placeholders and add the required query parameters from the Inputs section before sending. ```shell curl --get 'https://api.monsterapi.co/twitter/api/trends/timeline' \ -H 'Authorization: Bearer ' ```