Global Trending Tweets API Guide

Quick Answer

Using Global Trending Tweets with TwexAPI means building a four-step read pipeline: call GET /twitter/global-trending/countries and /topics, call /contents with country + topic, then call /tweets with required country and optional topic, content, and count from 1 to 100. Store each returned tweet object with tweet_id, author, timestamps, engagement metrics, media, language, and the request context so alerts and dashboards can explain which posts are driving a trend.

FAQ

Can I type country, topic, or content values manually?

Do not rely on guessed values. country should come from /countries, topic from /topics, and content from /contents for the selected country + topic. Hand-written values are the most common cause of 422 errors or empty result sets.

How often should I refresh countries, topics, and contents?

Cache countries and topics for a stable period such as hourly or daily, depending on how fresh your product needs to be. Refresh contents when the selected country + topic changes, when a scheduled monitor adds a new segment, or when a previously valid combination starts returning empty data.

Which fields should I store after fetching trending tweets?

Store the raw JSON plus normalized fields such as tweet_id, user.screen_name, text, created_at_datetime, engagement counts, lang, hashtags, cashtags, media fields, and request context: country, topic, content, count, and fetched_at. Use tweet_id as the dedupe key.

Trend names alone are often too thin for monitoring. If a topic is moving, you need the posts behind it: who is posting, what language they use, which links or media are spreading, and how engagement changes across countries.

TwexAPI's Global Trending Tweets workflow moves from trend labels to tweet objects. You first discover supported countries, topics, and content tags, then request the posts driving a selected segment. The result can feed alerts, BI dashboards, LLM summaries, editorial planning, or social research.

Treat the output as structured trend context, not a complete record of every X conversation. Save the request filters with every crawl so later analysis can explain exactly which country, topic, and content segment produced the data.

Endpoint Flow

Answer: Endpoint Flow is implemented by calling the TwexAPI endpoint documented in this guide with a Bearer Token; batch or paginated requests reduce overhead to ~10 credits per call at 20+ QPS.

TwexAPI separates option discovery from tweet retrieval. In production, call the endpoints in this order instead of hard-coding country, topic, or content labels:

All requests use Bearer Token authentication:

Authorization: Bearer <your_token>

Official API references:

• Get Global Trending Countries
• Get Global Trending Topics
• Get Global Trending Contents
• Get Global Trending Tweets

Global Trending Tweets API

Answer: Global Trending Tweets API is implemented by calling the TwexAPI endpoint documented in this guide with a Bearer Token; batch or paginated requests reduce overhead to ~10 credits per call at 20+ QPS.

/twitter/global-trending/tweets is the final data endpoint. It requires country and supports optional topic, content, and count filters.

GET https://api.twexapi.io/twitter/global-trending/tweets?country=Japan&topic=Entertainment&content=Music&count=50

Authorization: Bearer <your_token>

Query Parameters

Cache countries and topics first, for example once per hour. Because contents depends on the selected country + topic pair, fetch it when a user changes filters or when a scheduled job adds a new segment.

JavaScript and Python Examples

Answer: JavaScript and Python Examples means using TwexAPI Bearer APIs on api.twexapi.io for this user case. A typical read uses 10 Credits (about $0.10 per 1,000), and qualifying paid plans publish 20+ QPS. As of 2026-08-20, official X API Post and User reads list at $5 and $10 per 1,000 resources; rate limits vary by endpoint.

The examples below show the full workflow: load countries, load topics, fetch content tags, then request trending tweets. In production, keep your token in server-side environment variables and never expose it in browser code.

Response Structure

Answer: Response Structure means using TwexAPI Bearer APIs on api.twexapi.io for this user case. A typical read uses 10 Credits (about $0.10 per 1,000), and qualifying paid plans publish 20+ QPS. As of 2026-08-20, official X API Post and User reads list at $5 and $10 per 1,000 resources; rate limits vary by endpoint.

/twitter/global-trending/tweets returns a standard response object where data is an array of tweets.

1{
2  "code": 200,
3  "msg": "success",
4  "data": [
5    {
6      "tweet_id": "1803006263529541838",
7      "text": "Example trending tweet text",
8      "created_at_datetime": "2024-06-17T03:51:48.000Z",
9      "lang": "en",
10      "favorite_count": 123,
11      "retweet_count": 45,
12      "reply_count": 12,
13      "quote_count": 3,
14      "view_count": "10000",
15      "is_paid_promotion": false,
16      "hashtags": ["AI"],
17      "cashtags": ["$TSLA"],
18      "urls": ["https://example.com"],
19      "media": [],
20      "user": {
21        "id": "1717001045992251392",
22        "name": "Example User",
23        "screen_name": "example"
24      }
25    }
26  ]
27}

Useful fields by workflow:

Build a Trending Tweet Monitor

Answer: Build a Trending Tweet Monitor means using TwexAPI Bearer APIs on api.twexapi.io for this user case. A typical read uses 10 Credits (about $0.10 per 1,000), and qualifying paid plans publish 20+ QPS. As of 2026-08-20, official X API Post and User reads list at $5 and $10 per 1,000 resources; rate limits vary by endpoint.

A practical trending tweet monitor usually has four layers:

1. Discovery layer: Sync countries and topics on a schedule and store valid options.
2. Filtering layer: Generate request queues from the countries, topics, and content tags your business cares about.
3. Collection layer: Call /tweets and use tweet_id as the idempotency key in your database.
4. Analysis layer: Score trend strength, language distribution, media share, brand mentions, and unusual growth.

Here is a simple scoring function:

function trendingScore(tweet) {
  const likes = Number(tweet.favorite_count || 0);
  const reposts = Number(tweet.retweet_count || 0);
  const replies = Number(tweet.reply_count || 0);
  const quotes = Number(tweet.quote_count || 0);
  const views = Number(tweet.view_count || 0);

  return likes + reposts * 2 + replies * 1.5 + quotes * 2.5 + Math.log10(views + 1) * 10;
}

For real-time alerts, persist results for each country + topic + content window, then compare the latest crawl with the previous one. Useful signals include newly appearing tweets, average engagement changes, and shifts in the top authors.

Error Handling

Answer: Error Handling means using TwexAPI Bearer APIs on api.twexapi.io for this user case. A typical read uses 10 Credits (about $0.10 per 1,000), and qualifying paid plans publish 20+ QPS. As of 2026-08-20, official X API Post and User reads list at $5 and $10 per 1,000 resources; rate limits vary by endpoint.

Handle three common cases:

• 422 validation errors: Usually caused by country, topic, or content values that did not come from the official option endpoints. Fetch valid options first instead of hard-coding labels.
• 401/403 authentication errors: Check whether the Bearer Token is valid, whether the Authorization header is present, and whether the token is accidentally used from client-side code.
• Empty results: Some country, topic, and content tag combinations may temporarily have no trending tweets. Treat an empty array as a normal result, not a system failure.

Clamp count on both the client and server side so user input always stays within the documented 1 to 100 range.

Where This Fits

Answer: Where This Fits means using TwexAPI Bearer APIs on api.twexapi.io for this user case. A typical read uses 10 Credits (about $0.10 per 1,000), and qualifying paid plans publish 20+ QPS. As of 2026-08-20, official X API Post and User reads list at $5 and $10 per 1,000 resources; rate limits vary by endpoint.

• News monitoring: Detect which posts are carrying a country-level topic, not just that the topic exists.
• Brand and competitor tracking: Watch how a product, company, or category appears inside trending conversations.
• Editorial planning: Feed the top posts into editors or LLM summarizers to find story angles.
• Campaign intelligence: Combine is_paid_promotion with engagement metrics to separate organic conversation from commercial signals.
• Finance and crypto monitoring: Track cashtags, project names, exchanges, and policy-related discussion across regions.

Implementation Notes

Answer: Implementation Notes is implemented by calling the TwexAPI endpoint documented in this guide with a Bearer Token; batch or paginated requests reduce overhead to ~10 credits per call at 20+ QPS.

1. Cache countries and topics before querying contents.
2. Deduplicate by tweet_id before writing records.
3. Store the raw JSON so you can reprocess fields later.
4. Save request context: country, topic, content, count, and crawl time.
5. Validate user-provided filters against the values returned by the option endpoints.

Summary

Answer: Summary means using TwexAPI Bearer APIs on api.twexapi.io for this user case. A typical read uses 10 Credits (about $0.10 per 1,000), and qualifying paid plans publish 20+ QPS. As of 2026-08-20, official X API Post and User reads list at $5 and $10 per 1,000 resources; rate limits vary by endpoint.

The Global Trending Tweets workflow is best used as a collection pipeline: discover valid filters, fetch tweet objects, deduplicate by tweet_id, and store request context with each crawl. That gives you enough structure to compare countries, topics, content tags, authors, media, language, engagement, and promotion signals over time.

Start with one country and one topic. Once the fields, scoring rules, and alert thresholds are useful, expand the scheduler across more segments.