---
title: "Get trends (optional date range and region)"
method: GET
path: "/v1/trends"
tags: ["Trends"]
---

# Get trends (optional date range and region)

`GET /v1/trends`

## Request

- Base URL: `https://api.virlo.ai`
- URL: `https://api.virlo.ai/v1/trends`
- Auth: HTTP bearer

Returns trend groups within a specified date range. Defaults to the last 24 hours and the 'global' region (the worldwide feed).

## Query parameters

- `region` string
- `start_date` string
- `end_date` string
- `limit` number
- `top_exemplars` number

## Response `200`

Successfully retrieved trend groups

- V1TrendsResponseDto
  - `data` V1TrendGroupDto[], required
    - `id` string, required
    - `title` string, required
    - `region` string, required: Region this trend group belongs to. 'global' is the default worldwide feed.
    - `local_date` string, nullable: Calendar day of this group in the region's local timezone. Null only for legacy groups predating regionalization.
    - `trends` V1TrendRankingDto[], required
      - `id` string, required
      - `trend_id` string, required
      - `trend_group_id` string, required
      - `ranking` number, required
      - `scrape_status` 'pending' | 'success' | 'failed', required: Status of the scrape job that links exemplar videos to this trend. `pending` while children are running, `success` when complete, `failed` if the scrape errored.
      - `exemplar_count` number, required: Total exemplar videos linked to this trend ranking (not capped by top_exemplars).
      - `top_exemplars` V1TrendExemplarVideoDto[], required: Top exemplar videos for this trend, ordered by views DESC. Capped per request by the `top_exemplars` query param.
        - `video_id` string, required
        - `url` string, nullable
        - `platform` 'tiktok' | 'youtube' | 'instagram'
        - `views` number, required
        - `thumbnail_url` string, nullable
        - `publish_date` string, nullable
        - `author` V1TrendExemplarAuthorDto
          - `username` string, nullable
          - `avatar_url` string, nullable
          - `verified` boolean, nullable
      - `detected_at` string, nullable: When this trend was first detected and entered its day container.
      - `last_seen_at` string, nullable: Last intra-day analysis run that re-confirmed this trend. Null when the trend was only seen once.
      - `origin_region_codes` string[], nullable: Provenance for cross-regional (e.g. 'global') trends: the regions whose independent detections evidenced this trend. Null for plain regional trends.
      - `global_confidence` number, nullable: Confidence (0-1) that this is genuinely the same cross-regional trend. Only set on synthesis-promoted global trends.
      - `velocity_today_count` number, nullable: Videos matching this trend in the last 24h at discovery time.
      - `velocity_median_views` number, nullable: Median exemplar views at discovery time.
      - `momentum` V1MomentumDto
        - `score` number, required: Normalized 0-1 heat derived from the current views/hour of the trend’s exemplars. Higher = hotter right now.
        - `status` 'new' | 'rising' | 'steady' | 'fading', required: Lifecycle status. `new` = just detected, `rising` = accelerating, `steady` = flat, `fading` = decelerating.
        - `views_per_hour` number, required: Instantaneous view growth of the tracked exemplars at the last snapshot.
        - `updated_at` string: When momentum was last recomputed (snapshot loop, ~2h cadence).
      - `trend` V1TrendDto, required
        - `id` string, required
        - `name` string, required
        - `description` string, required
        - `trend_type` string, required

## Other responses

- `401`: Unauthorized - missing or invalid API key
- `429`: Too many requests - rate limit exceeded

---

[API](https://skmtc.dev/virlo/apis/virlo-public-api.md) · [All operations](https://skmtc.dev/virlo/apis/virlo-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/virlo/apis/virlo-public-api/revisions/3b69c6145087?raw)