---
title: "Query trends for an agent"
method: GET
path: "/v1/agents/{id}/trends"
tags: ["Content Research Agents"]
---

# Query trends for an agent

`GET /v1/agents/{id}/trends`

## Request

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

Paginated list of every trend row produced for this agent, newest first. Use `stable_key` to isolate a specific recurring trend, or `start_date`/`end_date` to window the results.

## Path parameters

- `id` string, required

## Query parameters

- `limit` number
- `page` number
- `stable_key` string
- `start_date` string
- `end_date` string

## Response `200`

Paginated trends

- AgentTrendsHistoryResponseDto
  - `data` V1TrendItemDto[], required
    - `id` string, required: Unique ID of this trend row in viral_insight_trends
    - `viral_insight_id` string, required: UUID of the viral_insights row (AI analysis batch) that produced this trend
    - `insight_type` 'custom_niche' | 'orbit', required
    - `reference_id` string, required: ID of the parent comet (custom_niche_configurations.id) or orbit (scraper_runs.id) this trend belongs to
    - `batch_start` string, required: Start of the collection window this trend was detected in (ISO-8601)
    - `batch_end` string, required: End of the collection window (ISO-8601)
    - `rank` number, required: Position of this trend within its batch (1 = strongest). Stable across requests for the same batch.
    - `stable_key` string, required: Stable identifier preserved across cycles when the same trend reappears. Use this to build a time series for a single trend.
    - `name` string, required
    - `why_it_works` string, nullable
    - `tactics` string[]: Specific creative tactics the LLM identified inside this trend
    - `confidence` number, nullable: 0–1 model confidence that this is a real, repeatable trend
    - `evidence_video_ids` string[]: IDs of videos from the batch that exemplify this trend. Guaranteed to be a subset of the analyzed batch.
    - `evidence_videos` object[], nullable: Enriched evidence video objects with id, url, and platform. NULL for trends created before this field was introduced. Use this to resolve video URLs directly without paginating orbit/comet videos.
    - `video_count` number, nullable
    - `total_views` number, nullable
    - `total_likes` number, nullable
    - `total_comments` number, nullable
    - `total_shares` number, nullable
    - `avg_virality_score` number, nullable
    - `platform_breakdown` object, nullable: Video counts keyed by platform (e.g. { "tiktok": 7, "youtube": 3, "instagram": 2 })
    - `top_creators` V1TrendTopCreatorDto[], nullable: Top creators driving this trend in the current batch
      - `username` string, nullable
      - `platform` string, nullable
      - `followers` number, nullable
      - `video_count` number, nullable
      - `total_views` number, nullable
    - `peak_hour_utc` number, nullable: Hour of day (UTC, 0-23) with the most evidence videos
    - `status` 'new' | 'rising' | 'steady' | 'fading', nullable: Classification vs. the previous cycle. `new` = not seen before, `rising`/`fading` = >=25% change in volume, `steady` otherwise.
    - `first_seen_at` string, nullable: Timestamp (ISO-8601) of the first cycle this trend was detected. Lets you compute how long a trend has been around.
    - `prev_video_count` number, nullable
    - `prev_total_views` number, nullable
    - `created_at` string, required
  - `pagination` PaginationMetaDto, required
    - `page` number, required
    - `limit` number, required
    - `total` number, required
    - `total_pages` number, required
    - `has_next_page` boolean, required
    - `has_prev_page` boolean, required

## Other responses

- `401`: Missing or invalid API key (`missing_api_key` / `invalid_api_key`)
- `404`: Agent not found
- `429`: Rate limit exceeded (`rate_limit_exceeded`); see the Retry-After header

---

[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)