---
title: "List an agent’s runs"
method: GET
path: "/v1/agents/{id}/runs"
tags: ["Content Research Agents"]
---

# List an agent’s runs

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

## Request

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

## Path parameters

- `id` string, required

## Query parameters

- `limit` number
- `page` number

## Response `200`

Runs

- AgentRunsListResponseDto
  - `data` AgentRunsListDataDto, required
    - `agent_id` string, uuid, required
    - `limit` number, required
    - `offset` number, required
    - `count` number, required
    - `runs` AgentRunDto[], required
      - `id` string, uuid, required
      - `agent_id` string, uuid, required
      - `status` 'pending' | 'processing' | 'completed' | 'partial_failure' | 'failed', required: `pending` and `processing` are in flight. `completed`, `partial_failure` and `failed` are final. `partial_failure` means one platform or keyword failed and the rest of the data is usable.
      - `total_videos_inserted` number, required
      - `total_videos_updated` number, required
      - `total_videos_failed` number, required
      - `videos_linked` number, required
      - `meta_ads_linked` number, required
      - `slideshows_linked` number, required
      - `youtube_count` number, required
      - `tiktok_count` number, required
      - `instagram_count` number, required
      - `exclude_keywords_filtered` number, required
      - `intent_filtered` number, required
      - `language_filtered_count` number, required
      - `duplicates_dropped` number, required
      - `outliers_identified` number, required
      - `trends_detected` string[], nullable
      - `keyword_breakdown` object[], nullable: Per-keyword collection breakdown. One entry per keyword with `keyword`, `videos_inserted`, `videos_updated`, and per-platform counts (`tiktok_count`, `youtube_count`, `instagram_count`). The fastest way to see which keywords are actually producing content.
      - `execution_time_ms` number, required
      - `created_at` string, required
      - `started_at` string, nullable
      - `completed_at` string, nullable

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