Twitter Trends API: From Detection to Evidence

A Twitter Trends API returns topics receiving unusual attention on X for a supported location. It is a discovery feed: useful for finding conversations that may deserve investigation, but incomplete as an explanation of what happened or why people care.

MintAPI's Twitter Trends endpoint accepts a country and returns a trends array. Each item can include a trend name, an optional description, and context such as a category. That response is a good trigger for research, monitoring, editorial, and agent workflows.

The key design choice comes after retrieval. Do not send the trend name straight to a dashboard with a confident summary. Search for the posts behind it, inspect representative examples, check the accounts driving the conversation, and preserve the evidence used for any conclusion.

A trending label establishes a narrow fact: the topic is being surfaced as a trend for the selected country at the time of the call. It does not establish positive sentiment, organic adoption, commercial intent, factual accuracy, or relevance outside X.

• A name can be ambiguous. A person, product, sports team, place, and meme may share the same phrase.
• A trend can be driven by criticism, jokes, breaking news, coordinated promotion, or several unrelated conversations.
• The loudest posts are not necessarily representative of the complete conversation.
• Country-level attention on X should not be presented as public opinion for that country.

This distinction is useful operationally. Treat the trend response as candidate generation and require a second retrieval stage before an alert, brief, or agent answer makes a stronger claim.

The endpoint uses the country name enum documented in the API reference. For example, use UnitedStates for the United States. Authentication can use a personal bearer API key, while agent runtimes can use request-based x402 payments.

1curl --request GET \2  --url 'https://api.mintapi.dev/api/twitter/trends?country=UnitedStates' \3  --header 'Authorization: Bearer YOUR_API_KEY'

Store the country, retrieval timestamp, rank or array position, name, description, and context with every snapshot. A trend list without a time and location is difficult to compare later. The endpoint is currently documented at 2 credits per successful call; check the API reference before setting a production polling budget.

A reliable workflow adds context in stages. Each call should answer a specific question and determine whether the candidate deserves the next request.

• Detect: fetch country trends and compare the snapshot with prior observations.
• Search: retrieve Top results for an overview, then Latest results when recency and sequence matter.
• Inspect: fetch tweet details for a small set of representative or influential posts.
• Verify: resolve author profiles and compare the trend with another source before making claims beyond activity on X.

MintAPI exposes each retrieval step separately. Use the Twitter Search endpoint for conversation samples, then use Tweet Info and User Info only for the records that matter.

Start with the exact trend name, but do not assume it is the final query. Hashtags can usually be searched directly. Plain phrases may need quotes, exclusions, or an adjacent term to separate unrelated meanings. Keep the original trend and the derived query as separate fields so the transformation remains auditable.

1const trendName = "Example Topic";2const url = new URL("https://api.mintapi.dev/api/twitter/search");34url.searchParams.set("query", trendName);5url.searchParams.set("search_type", "Top");67const response = await fetch(url, {8  headers: {9    Authorization: `Bearer ${process.env.MINTAPI_API_KEY}`,10  },11});1213if (!response.ok) {14  throw new Error(await response.text());15}1617const searchResult = await response.json();

The search response includes a timeline and may return anext_cursor. Begin with one bounded page. Pagination is justified when the first page is relevant and the downstream question requires a larger sample—not simply because another cursor exists.

The Search endpoint supports Top, Latest,Media, People, and Lists. Trend validation usually starts with Top or Latest, but they answer different questions.

• Top: find prominent posts and recognizable explanations of the topic.
• Latest: inspect current usage, emerging context, and whether the conversation is still active.
• Media: investigate when images or video are central to the event or narrative.
• People: resolve cases where the trending phrase may refer to a person or account.

Comparing Top and Latest is more informative than treating either as a neutral sample. Top can overrepresent posts that already attracted engagement. Latest can contain more noise and repetition. Record which mode produced each item.

A useful evidence score describes the quality of the material you collected. It should not pretend to reverse-engineer X's ranking system. Keep the criteria simple enough to explain in a report.

• Relevance: how many sampled posts clearly refer to the same topic?
• Recency: are relevant posts still appearing in Latest search?
• Source diversity: does the sample include independent authors rather than repeated copies from one cluster?
• Context agreement: do the trend description, search results, and inspected posts point to the same event?
• External confirmation: does a primary source or another credible dataset support claims that extend beyond X activity?

Save counts and examples behind the score. A label such as “high confidence” is only useful if another person can inspect the search mode, sample size, timestamps, author set, and source links that produced it.

One response tells you what is trending now. Repeated snapshots tell you what changed. Use a schedule appropriate to the decision and avoid polling simply for the sake of collecting data.

• Create a stable normalized key while retaining the original capitalization and hashtag form.
• Record first seen, last seen, country, rank, description, and context for each observation.
• Mark entries as new, persistent, rising, falling, or no longer present based on your own snapshot history.
• Trigger search only for new entries, meaningful rank changes, or topics on a maintained watchlist.

These labels describe changes in your stored observations, not hidden platform metrics. For a broader event-driven design, see the guide to Twitter monitoring agents.

An agent can triage a trend list, choose candidates relevant to its assignment, and request supporting posts. The runtime—not the prompt— should own authentication, payment, retries, rate controls, and the maximum number of follow-up calls.

1import {2  createAgentClient,3  createSignerResolver,4} from "@mintapi/gateway/client";56const signerResolver = createSignerResolver({7  signerResolversByFamily: {8    evm: async ({ network }) => resolveManagedEvmSigner(network),9    svm: async ({ network }) => resolveManagedSolanaSigner(network),10  },11});1213const client = createAgentClient({14  baseUrl: "https://api.mintapi.dev",15  getSigner: signerResolver,16});1718const trends = await client.twitter.trends({19  country: "UnitedStates",20});

Require the agent's output to separate observation from inference. A compact record can include the detected trend, country, retrieval time, derived query, representative post IDs, relevant authors, confidence notes, and external sources. The agent quickstart and paid fetch guide explain the request-based payment flow.

• Calling a trend positive or negative before reading posts from the conversation.
• Using one viral post as proof that the entire trend has the same cause.
• Comparing countries without storing the country value and collection time.
• Paginating every search result before checking whether the query is ambiguous.
• Giving an LLM raw posts without IDs, timestamps, authors, or source links it can cite.
• Publishing an X trend as a claim about the general population without external validation.

Trend detection is strongest as the top of a retrieval funnel. Use it to find unexpected topics, search to collect context, tweet details to preserve important records, and profile data to understand who is contributing to the conversation.

For workflows centered on amplification, replies, and narrative movement, continue with Twitter API social signal agents. For deeper subject investigation, use the Twitter agent research workflow. To compare public-data retrieval with the official platform API, read the Twitter API alternative comparison.

Start with the Trends API reference, run one country-level request, and define the evidence required before your workflow escalates a candidate.