APITube Help Center

How to Discover Trending Topics and Entities

Use /v1/news/trends to rank the top entities, categories, topics and sources in your results

Tasha Tatum

Written by Tasha Tatum

June 26, 2026

Open this example in the API Playground ↗

How to discover trending topics and entities

To find what is trending — the most-covered entities, categories, topics, industries or sources — call the /v1/news/trends endpoint with a field to aggregate on. It runs a grouped count over the articles that match your filters and returns the top values ranked by how many articles mention each one. This returns the top 10 trending entities in technology coverage:

curl "https://api.apitube.io/v1/news/trends?field=entity.id&per_page=10&title=technology&api_key=YOUR_API_KEY"

You can pass the key as the api_key query parameter or as an X-API-Key header, and call the endpoint with GET (filters as query parameters) or POST (filters as a JSON body).

Which fields can you trend on?

The field parameter is required and decides what gets ranked. Five fields are allowed:

  • entity.id — trending people, companies, locations and other entities (enriched with name, type and Wikidata id)
  • category.id — trending IPTC categories (enriched with name and taxonomy)
  • topic.id — trending topics
  • industry.id — trending industries
  • source.id — trending sources (enriched with name and domain)

You can aggregate up to 5 fields in one call by passing them comma-separated, for example field=entity.id,category.id. An unknown or missing field returns error ER0350.

Trends are computed over the articles your filters select, so every standard search filter works here too — title, language.code, source.domain, published_at.start, published_at.end and the rest. Add the filters you would use for a normal search, and the ranking covers exactly that slice. This finds the top categories in English-language news from the last 7 days:

curl "https://api.apitube.io/v1/news/trends?field=category.id&language.code=en&published_at.start=NOW-7DAYS&api_key=YOUR_API_KEY"

If you do not pass any dates, the endpoint defaults to the last 30 days. The date range is also capped at 30 days — a wider span returns error ER0353. For the full filter list, see the Searching & Filtering News section, including How to filter news by date range.

A single-field response carries the request echo plus a trends array, ranked by count (descending) by default:

{
  "status": "ok",
  "field": "entity.id",
  "per_page": 10,
  "offset": 0,
  "total_count": 842,
  "total_articles": 15730,
  "sort": "count",
  "order": "desc",
  "mincount": 1,
  "trends": [
    {
      "value": { "id": 1599, "name": "OpenAI", "type_id": 3, "wikidata_id": "Q21708200" },
      "count": 412,
      "percentage": 2.62,
      "growth_rate": 5.1
    }
  ],
  "request_id": "5e9c3a17-8b2d-4f61-9a04-7d1e6c8b3f92"
}

For each trend, count is how many matching articles reference the value, percentage is its share of all matching articles, and growth_rate is the publication velocity (articles per hour between the first and last article seen). total_count is the number of distinct values found and total_articles is the size of the filtered set.

How to control the ranking and size

A few parameters shape the list:

  • per_page — how many top values to return per field (default 10, max 100).
  • offset — skip results for pagination (default 0).
  • sort — count (default), value (alphabetical) or growth_rate.
  • order — desc (default) or asc.
  • mincount — drop values with fewer than N articles (default 1, max 10000); useful to cut noise from long-tail mentions.

Popularity and momentum are different questions. Add trending=true to compute a trending score for each value: the ratio of its recent 2-day average to its 14-day average, so a score above 1 means rising and below 1 means declining. Each trend then also includes trending_history (daily counts). Tune the window with trending_days (default 14, between 7 and 30):

curl "https://api.apitube.io/v1/news/trends?field=entity.id&trending=true&trending_days=14&api_key=YOUR_API_KEY"

By default the values come back ordered by article count. Sorting directly by the trending score requires compare mode: combine trending=true with compare=true (and a compare_window) and then add sort=trending_score — on a plain trending request that sort is ignored and results stay ordered by count.

To compare two periods directly, use compare=true with a compare_window such as 7DAYS (required, else error ER0352). Each trend then gains previous_count, change_absolute and change_percent, and sort=change orders by the biggest movers.

Each /v1/news/trends call costs 1 point, no matter how many fields you aggregate or how large the matching set is. On a test key the structure and counts come back, but each trend value is replaced with the placeholder [Upgrade subscription plan] — switch to a live key to see real entity and category values.

Common Questions

Yes. Pass up to five comma-separated values in field, for example field=entity.id,category.id,source.id. The response then returns a trends object keyed by field name, each holding its own ranked array, so one request can power an entity list, a category breakdown and a source breakdown together.

Why is per_page capped at 100?

The trends endpoint returns aggregated top values, not raw articles, so per_page is limited to 100 results per field (default 10). This differs from the article search endpoints. If you need to walk further down the ranking, increase offset and request the next slice.

Trends are computed over a rolling window of at most 30 days. Omit the dates to use the default last-30-days window, or set published_at.start / published_at.end within a 30-day span. A wider range returns error ER0353, so split long studies into 30-day chunks.

Beyond the field and date errors above, the usual API codes apply: ER0201/ER0202 (HTTP 401) when the API key is missing or invalid, ER0176 (HTTP 402) when your account has no points left, and ER0203 (HTTP 429) when you exceed the rate limit of 50 requests per minute on a live key (15 on a test key). Repeated violations trigger a temporary ban (ER0204). Every response includes the request_id for tracing.

Related Articles