Content Research Agents

Get an agent’s videos

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

get/v1/agents/{id}/videos

Request

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

Path parameters

idstring required

Agent UUID

Query parameters

limitnumber
Example:50

Maximum number of items to return. Values above 100 are clamped to 100 rather than rejected.

pagenumber
Example:1

Page number for pagination

min_viewsnumber
Example:100000

Minimum view count filter (read-time).

platformsstring[]

Filter by platform(s).

start_datestring
Example:2026-01-01T00:00:00Z

Only videos published on/after this date (ISO string).

end_datestring
Example:2026-06-30T23:59:59Z

Only videos published on/before this date (ISO string).

order_by'publish_date' | 'views' | 'created_at'

Field to sort by.

sort'asc' | 'desc'

Sort direction.

intent_matchboolean

Filter by intent-match result. Only meaningful when the agent used data_intelligence_enabled. true = matching only, false = non-matching.

regionstring
Example:US

Filter by resolved upload region (ISO-3166-1 alpha-2, e.g. US, CA, RU, AU). Case-insensitive; normalized to uppercase.

include_transcriptboolean

Add a transcript object to every video on the page: { text, segments, source }. source: "transcribed" is Virlo speech-to-text of the audio (run by Data Intelligence) and carries timed segments in seconds; source: "platform" is the transcript TikTok or YouTube published, usually plain text with segments: null (a small share carry timings, so check segments rather than source). transcript is null when the video has no speech or has not been transcribed yet. Instagram Reels only get transcripts on agents with data_intelligence_enabled. Free. A page with transcripts is several times larger, so keep limit small.

Response

Videos

Example response

{
  "data": {
    "videos": [
      {
        "platform": "tiktok",
        "duration": 34,
        "author": {
          "username": "creator_handle",
          "avatar_url": "https://auth.virlo.ai/storage/v1/object/public/avatars/abc.jpg",
          "followers": 160726,
          "country": "US"
        },
        "sound": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "external_id": "7559312683885201425",
          "title": "Chopin Nocturne No. 2 Piano Mono",
          "platform": "tiktok",
          "duration": 246,
          "cover_url": "https://auth.virlo.ai/storage/v1/object/public/sound-covers/6e03a216-f8c8-40e9-ba9b-b79d8a287b57.jpg",
          "owner_handle": "@someone",
          "owner_nickname": "Someone",
          "usage_count": 5999231
        },
        "transcript": {
          "segments": [
            {
              "start": 0.64,
              "end": 3.52
            }
          ]
        }
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.