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

# Get an agent’s videos

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

## Request

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

Videos collected by the agent. Apply read-time filters here (min_views, date window, platform, sort) — this is the intended place to narrow the broad collection. Every video carries `duration` (seconds, null when unknown). Pass `include_transcript=true` to add each video’s `transcript` (text, plus timed segments when the transcript has timings).

## Path parameters

- `id` string, required

## Query parameters

- `limit` number
- `page` number
- `min_views` number
- `platforms` string[]
- `start_date` string
- `end_date` string
- `order_by` 'publish_date' | 'views' | 'created_at'
- `sort` 'asc' | 'desc'
- `intent_match` boolean
- `region` string
- `include_transcript` boolean

## Response `200`

Videos

- AgentVideosResponseDto
  - `data` AgentVideosDataDto, required
    - `agent_id` string, uuid, required
    - `agent_name` string, nullable
    - `total` number, required
    - `limit` number, required
    - `offset` number, required
    - `videos` AgentVideoItemDto[], required
      - `id` string, uuid, required
      - `url` string, required
      - `description` string, nullable
      - `platform` string, required: Platform identifier (tiktok | youtube | instagram)
      - `views` number, required
      - `likes` number, required
      - `shares` number, required
      - `comments` number, required
      - `bookmarks` number, nullable
      - `publish_date` string, nullable
      - `duration` number, nullable: Video length in whole seconds. Null when the platform did not report one. Not the same as `sound.duration`, which is the length of the audio track.
      - `author` V1AuthorDto
        - `username` string, required
        - `avatar_url` string, nullable, required: Creator avatar URL. Always an absolute URL (or null). Images Virlo stores are served from https://auth.virlo.ai/storage/v1/object/public/<bucket>/; platform CDN links are passed through. Some files are HEIC, which most non-Safari browsers cannot render, so convert before display if you need to.
        - `followers` number, required
        - `verified` boolean, required
        - `country` string, nullable: Creator's country (ISO-3166-1 alpha-2), when the platform exposes it. Distinct from a video's `upload_region`.
      - `hashtags` string[]
      - `thumbnail_url` string, nullable
      - `keyword_found_by` string, nullable
      - `is_duet` boolean, nullable
      - `is_stitch` boolean, nullable
      - `upload_region` string, nullable
      - `upload_region_source` string, nullable
      - `intelligence` object, nullable
      - `intelligence_status` 'ready' | 'pending' | 'disabled' | 'failed' | 'skipped': Disambiguates a null `intelligence` field: `ready`, `pending`, `disabled` (data_intelligence_enabled was off), `skipped` (deliberately not analyzed, so it will never arrive; see `intelligence_skip_reason`), `failed` (reserved).
      - `intelligence_skip_reason` 'intent_mismatch' | 'too_old' | 'under_followers', nullable: Set only when `intelligence_status` is `skipped`: why Data Intelligence deliberately did not analyze this item, so its `intelligence` will never arrive. `intent_mismatch` (it does not match the agent's intent), `too_old` (published more than a year ago and not among the run's top performers), `under_followers` (more than two days old with no more views than its creator has followers). null otherwise.
      - `intent_match` AgentIntentMatchDto
        - `matches` boolean, required
        - `reasoning` string, nullable
      - `sound` V1SoundDto
        - `id` string, required: Virlo's internal sound ID (UUID). Use this for the /v1/sounds/:sound_id family (details, videos, usage-history, resolve). For the satellite sound lookup prefer `external_id`, though passing this UUID also works — it is auto-resolved to the sound's platform + external_id.
        - `external_id` string, nullable: Platform-native sound identifier (TikTok music/clip id, or Instagram audio id). This is the `music_id` accepted by the satellite sound lookup — call GET /v1/satellite/sounds/{platform}/{external_id} for TikTok or Instagram sounds. YouTube sounds are not supported (you'll get a 400). Null for sounds without a platform id.
        - `title` string, required
        - `platform` 'tiktok' | 'youtube' | 'instagram', required
        - `duration` number, nullable: Duration in seconds. Available on TikTok only.
        - `cover_url` string, nullable: Sound cover image URL. Available on TikTok and YouTube. Always an absolute URL (or null). Images Virlo stores are served from https://auth.virlo.ai/storage/v1/object/public/<bucket>/; platform CDN links are passed through. Some files are HEIC, which most non-Safari browsers cannot render, so convert before display if you need to.
        - `owner_handle` string, nullable: Sound owner handle. Partially available on TikTok (~12%).
        - `owner_nickname` string, nullable: Sound owner display name. Available on TikTok, YouTube, Instagram.
        - `is_original` boolean, nullable: Whether the sound is an original creation. TikTok only.
        - `is_commerce_music` boolean, nullable: Whether the sound is cleared for commercial use. TikTok only.
        - `usage_count` number, nullable: Platform-wide usage count. TikTok only.
      - `transcript` AgentVideoTranscriptDto
        - `text` string, required: The full transcript.
        - `segments` AgentTranscriptSegmentDto[], nullable: Timed segments, or null when the transcript has no timings. Always present when `source` is `transcribed`. Usually null for `platform` transcripts, which are mostly published as plain text; a small share carry timings. Check this field rather than inferring it from `source`.
          - `start` number, required: Seconds from the start of the video.
          - `end` number, required
          - `text` string, required
        - `source` 'transcribed' | 'platform', required: `transcribed`: Virlo speech-to-text of the audio (run by Data Intelligence; the only source for Instagram Reels). `platform`: the transcript TikTok or YouTube published. When both exist, `transcribed` is returned.

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