Trends

Trending topics organized into daily groups, available globally and per region. Each group contains ranked trends with detail about the content driving them.

Endpoint	Cost
`GET /v1/trends`	$0.25
`GET /v1/trends/digest`	$0.25
`GET /v1/trends/emerging`	$0.25 (rate-limited)
`GET /v1/trends/regions`	Free

Regions

Trends are detected per region. Every region has its own curated battery of sources and its own timezone-aware schedule, so a region's trends reflect what is actually resonating with that audience — not a filtered view of a single worldwide feed.

Currently supported regions:

Name
global
Type
string
Description
The worldwide feed. This is the default when no region is passed, and it preserves the exact historical behavior of these endpoints — existing integrations keep working unchanged.
Name
us
Type
string
Description
United States — American pop culture, US news moments, sports, creators and humor.
Name
gb
Type
string
Description
United Kingdom — British pop culture, UK news moments, football, creators and humour.
Name
au
Type
string
Description
Australia — Aussie pop culture, AU news moments, sports (AFL/NRL/cricket), creators and humour.

More regions — including sub-regions such as major city hubs — will be added over time. Query GET /v1/trends/regions (free) to discover the currently available codes programmatically instead of hard-coding this list.

How often trends are raised

Each region runs three times per day at 7:00, 13:00 and 19:00 in its own local timezone, so trends are caught as they emerge across the day.
All runs for the same region-local day merge into one trend group per region per day. Re-detected trends are deduplicated rather than duplicated.
Every trend carries detected_at (when it first entered the day's group) and last_seen_at (the most recent run that re-confirmed it) — useful for spotting brand-new versus sustained trends.
Trends detected independently in multiple country regions are promoted into the global feed with origin_region_codes (e.g. ["gb", "us"]) and a global_confidence score between 0 and 1. Trends detected natively carry null in both fields.
Passing an unknown region code returns a 400 listing the available codes.

Momentum & lifecycle

Beyond the daily ranking, every trend carries a momentum signal describing how fast it is moving right now. Between the 3x/day discovery runs, a lightweight background loop re-reads the view and like counts of each trend's top exemplars (roughly every 2 hours, configurable per region) and recomputes momentum — no re-clustering, no AI, so it stays cheap and fresh.

Each trend exposes a momentum object:

Name
momentum.status
Type
string
Description
Lifecycle status — one of new (just detected), rising (accelerating), steady (holding), or fading (decelerating). This is the vocabulary the emerging endpoint filters on.
Name
momentum.score
Type
number
Description
Normalized 0–1 heat derived from the current view growth of the trend's exemplars. Higher means hotter. Use it to rank trends by how live they are.
Name
momentum.views_per_hour
Type
number
Description
Instantaneous exemplar view growth measured at the last snapshot.
Name
momentum.updated_at
Type
string
Description
When momentum was last recomputed (ISO 8601).

momentum is null until the first snapshot runs for a freshly detected trend. Until then, a trend's lifecycle is seeded from discovery-time signals, so GET /v1/trends/emerging is useful immediately.

GET/v1/trends

Get trends

Returns trend groups within a specified date range. Each group contains ranked trends that were active at that time. Defaults to the last 24 hours and the global region. Each region produces one trend group per region-local day, refreshed three times per day (see Regions).

Cost per request:$0.25

Query parameters

Name
region
Type
string
Description
Trend region code (see Regions). Defaults to global — the worldwide feed, preserving the historical behavior of this endpoint. Pass a country code like us, gb or au for region-specific trends. Unknown codes return a 400 listing the available regions.
Name
start_date
Type
string
Description
Start date for filtering (ISO 8601 format like 2026-07-14T00:00:00.000Z or simplified 2026-07-14). Defaults to 24 hours ago.
Name
end_date
Type
string
Description
End date for filtering (ISO 8601 format like 2026-07-16T23:59:59.999Z or simplified 2026-07-16). Defaults to now.
Name
limit
Type
number
Description
Maximum number of trend groups to return (1-100). Default is 50.

Regional response fields

Name
region
Type
string
Description
The region code the trend group belongs to.
Name
local_date
Type
string
Description
The region-local calendar date the group covers (YYYY-MM-DD).
Name
detected_at
Type
string
Description
When the trend was first detected and entered the day's group.
Name
last_seen_at
Type
string
Description
The most recent intra-day run that re-confirmed the trend.
Name
origin_region_codes
Type
array | null
Description
Only set on global trends promoted by cross-region synthesis — the country regions the trend was independently detected in (e.g. ["gb", "us"]). null for natively detected trends.
Name
global_confidence
Type
number | null
Description
Confidence score (0-1) for synthesis-promoted global trends. null for natively detected trends.
Name
momentum
Type
object | null
Description
Live momentum signal (status, score, views_per_hour, updated_at) — see Momentum & lifecycle. null until the first snapshot runs for the trend.

Request

GET

/v1/trends

curl -G https://api.virlo.ai/v1/trends \
  -H "Authorization: Bearer {token}" \
  -d region=gb \
  -d start_date=2026-07-14 \
  -d end_date=2026-07-16 \
  -d limit=50

Response

{
  "data": [
    {
      "id": "337fe759-a835-4d77-9d84-f99877685b63",
      "title": "Trends for Jul 7th",
      "region": "gb",
      "local_date": "2026-07-07",
      "trends": [
        {
          "id": "9e1cd3be-4eff-4418-8e19-30ab10f74a6b",
          "trend_id": "ddb9c022-7448-42d9-b440-c7ecaaa011a4",
          "trend_group_id": "337fe759-a835-4d77-9d84-f99877685b63",
          "ranking": 1,
          "detected_at": "2026-07-06T23:22:06.846Z",
          "last_seen_at": "2026-07-06T23:22:06.846Z",
          "origin_region_codes": null,
          "global_confidence": null,
          "momentum": {
            "status": "rising",
            "score": 0.74,
            "views_per_hour": 18400,
            "updated_at": "2026-07-07T13:00:00.000Z"
          },
          "trend": {
            "id": "ddb9c022-7448-42d9-b440-c7ecaaa011a4",
            "name": "England Defeats Mexico 3-2 in Dramatic World Cup Round of 16 Match",
            "description": "England defeated Mexico 3-2 in a dramatic Round of 16 match at the Azteca Stadium, with Jude Bellingham scoring twice in just 98 seconds. Harry Kane also converted a penalty, helping England overcome a red card and secure their place in the quarter-finals.",
            "trend_type": "content"
          }
        },
        {
          "id": "04863618-8055-4eeb-8f5e-874bdec0d11b",
          "trend_id": "21973a42-792f-4a4a-a6b9-6dbfed2bfe5a",
          "trend_group_id": "337fe759-a835-4d77-9d84-f99877685b63",
          "ranking": 2,
          "detected_at": "2026-07-06T23:22:06.846Z",
          "last_seen_at": "2026-07-06T23:22:06.846Z",
          "origin_region_codes": null,
          "global_confidence": null,
          "trend": {
            "id": "21973a42-792f-4a4a-a6b9-6dbfed2bfe5a",
            "name": "Sky's £1.6 Billion Takeover of ITV Broadcasting and Streaming",
            "description": "Sky announced a £1.6 billion deal to acquire ITV's broadcasting and streaming business, which includes ITV's television channels and the ITVX streaming service. This significant acquisition aims to create a stronger competitor against global streaming giants like Netflix and Disney+.",
            "trend_type": "content"
          }
        }
      ]
    }
  ]
}

GET/v1/trends/digest

Get trends digest

Returns today's trend groups for a region, based on the current date in that region's own timezone. This ensures that late in the region's evening you still get that region's "today" — for example, at 9pm in London the gb digest still returns July 7th's UK trends even though a new UTC day may have started elsewhere.

Cost per request:$0.25

Query parameters

Name
region
Type
string
Description
Trend region code (see Regions). Defaults to global. Pass a country code like us, gb or au for region-specific trends.
Name
limit
Type
number
Description
Maximum number of trend groups to return (1-100). Default is 50.

The response shape is identical to Get trends, including the regional fields (region, local_date, detected_at, last_seen_at).

Request

GET

/v1/trends/digest

curl -G https://api.virlo.ai/v1/trends/digest \
  -H "Authorization: Bearer {token}" \
  -d region=au

Response

{
  "data": [
    {
      "id": "193eee1c-d33f-4555-86c8-c28a65018bdf",
      "title": "Trends for Jul 7th",
      "region": "au",
      "local_date": "2026-07-07",
      "trends": [
        {
          "id": "362ba34d-d78d-46bd-8891-e9777d07eac3",
          "trend_id": "f24b6a0f-b316-4e64-98c8-316d9c170302",
          "trend_group_id": "193eee1c-d33f-4555-86c8-c28a65018bdf",
          "ranking": 1,
          "detected_at": "2026-07-07T01:34:41.987Z",
          "last_seen_at": "2026-07-07T01:34:41.987Z",
          "origin_region_codes": null,
          "global_confidence": null,
          "trend": {
            "id": "f24b6a0f-b316-4e64-98c8-316d9c170302",
            "name": "Tasmania's One-Tonne Internet Star Returns",
            "description": "Neil the elephant seal, a one-tonne marine mammal, has returned to Tasmania, captivating audiences with his antics and garnering a massive social media following of 1.4 million on TikTok. His recent visit has led to significant public attention, with videos of him causing chaos going viral.",
            "trend_type": "content"
          }
        },
        {
          "id": "72ebe294-da90-483a-a687-0a0fea4e2f6e",
          "trend_id": "44f18ae9-da5a-42fe-ba69-3a4432286c99",
          "trend_group_id": "193eee1c-d33f-4555-86c8-c28a65018bdf",
          "ranking": 2,
          "detected_at": "2026-07-07T01:34:41.987Z",
          "last_seen_at": "2026-07-07T01:34:41.987Z",
          "origin_region_codes": null,
          "global_confidence": null,
          "trend": {
            "id": "44f18ae9-da5a-42fe-ba69-3a4432286c99",
            "name": "Folarin Balogun Red Card Appeal & World Cup Drama",
            "description": "FIFA lifted Folarin Balogun's one-game suspension for a red card received during the U.S. men's national team's match against Bosnia and Herzegovina, allowing him to play in the Round of 16 against Belgium. The reversal has sparked massive debate across football communities.",
            "trend_type": "content"
          }
        }
      ]
    }
  ]
}

GET/v1/trends/emerging

Get emerging trends

Returns the trends that are emerging right now in a region — those with a new or rising lifecycle status — ranked by live momentum heat. This is the "what's about to take off" view: a user can pull the early-stage trends so they can act while opportunity is high and competition is low.

It reads the same broad, no-keywords-required feed as the digest, filtered to early-stage trends and ordered by momentum. Because momentum is maintained by the background snapshot loop, this endpoint only reads already-computed state and responds fast. It composes with region — e.g. region=gb answers "what's emerging in the UK right now".

Intended for user-triggered, in-product use, so it is rate-limited per plan (per-minute, per-hour and per-day windows) in addition to costing $0.25 (25 credits) per call — the same as /v1/trends and /v1/trends/digest.

Query parameters

Name
region
Type
string
Description
Trend region code (see Regions). Defaults to global. Compose with a country code like gb or au for market-specific emerging trends.
Name
limit
Type
number
Description
Maximum number of emerging trends to return (1-50). Default is 20.
Name
top_exemplars
Type
number
Description
Top N exemplar videos per trend, ordered by views (0-20). Use 0 to omit exemplars. Default is 5.

Response fields

Returns a flat list of emerging trends (not grouped by day). Each item carries status, momentum_score, views_per_hour, detected_at, last_seen_at, exemplar_count, top_exemplars and the trend object, plus the top-level region and generated_at.

Request

GET

/v1/trends/emerging

curl -G https://api.virlo.ai/v1/trends/emerging \
  -H "Authorization: Bearer {token}" \
  -d region=gb \
  -d limit=20

Response

{
  "region": "gb",
  "generated_at": "2026-07-07T14:22:11.000Z",
  "data": [
    {
      "id": "9e1cd3be-4eff-4418-8e19-30ab10f74a6b",
      "trend_id": "ddb9c022-7448-42d9-b440-c7ecaaa011a4",
      "ranking": 3,
      "region": "gb",
      "status": "rising",
      "momentum_score": 0.74,
      "views_per_hour": 18400,
      "detected_at": "2026-07-07T09:12:03.000Z",
      "last_seen_at": "2026-07-07T13:04:41.000Z",
      "exemplar_count": 42,
      "top_exemplars": [],
      "trend": {
        "id": "ddb9c022-7448-42d9-b440-c7ecaaa011a4",
        "name": "Wimbledon Round-of-16 Upset",
        "description": "A qualifier knocked out the No. 2 seed in five sets, and clips of the final point are spreading fast across UK sports pages.",
        "trend_type": "content"
      }
    }
  ]
}

GET/v1/trends/regions

List regions

Returns the trend regions that can be passed as the region query parameter on /v1/trends and /v1/trends/digest. This endpoint is free — use it to discover new regions as they become available rather than hard-coding the list.

Request

GET

/v1/trends/regions

curl https://api.virlo.ai/v1/trends/regions \
  -H "Authorization: Bearer {token}"

Response

{
  "data": [
    { "code": "global", "name": "Global", "timezone": "America/New_York" },
    { "code": "us", "name": "United States", "timezone": "America/New_York" },
    { "code": "gb", "name": "United Kingdom", "timezone": "Europe/London" },
    { "code": "au", "name": "Australia", "timezone": "Australia/Sydney" }
  ]
}

Error responses

The trends endpoints may return the following error codes:

Name
400 Bad Request
Description
Invalid parameters provided. Common causes include: - Invalid date format (must be ISO 8601 format for /v1/trends) - Invalid limit value (must be 1-100)
- Unknown region code (the error message lists the available codes)
Name
401 Unauthorized
Description
Missing or invalid API key. Ensure you're including your API key in the Authorization header.
Name
402 Payment Required
Description
Insufficient prepaid balance. Add funds at dev.virlo.ai/dashboard/billing.
Name
429 Too Many Requests
Description
Rate limit exceeded. Your plan has specific rate limits per endpoint. Wait before making additional requests.