Social video research API

What to build with it

Create a research agent with a specific topic and platform scope.
Read the finished run before paging through its videos.
Keep the agent and run IDs with each video so the selection can be explained later.

Provider reference: Virlo documentation. Authentication uses a provider-issued Bearer token, stored on your server.

Endpoints and inputs

1 documented operation. Query and path fields are listed separately from JSON request-body fields.

GET/v1/agents/{id}/videos

Path and query parameters

id: string (path) · required
limit: number (query) · optional · default: 50 · minimum: 1 · maximum: 100
page: number (query) · optional · default: 1 · minimum: 1
min_views: number (query) · optional
platforms: array (query) · optional
start_date: string (query) · optional
end_date: string (query) · optional
order_by: string (query) · optional · values: publish_date, views, created_at
sort: string (query) · optional · values: asc, desc · default: "desc"
intent_match: boolean (query) · optional
region: string (query) · optional
include_transcript: boolean (query) · optional · default: false

Documented response fields

data: object · required
data.agent_id: string · required
data.agent_name: string | null · optional
data.total: number · required
data.limit: number · required
data.offset: number · required
data.videos: array · required
data.videos[].id: string · required
data.videos[].url: string · required
data.videos[].description: string | null · optional
data.videos[].platform: string · required
data.videos[].views: number · required
data.videos[].likes: number · required
data.videos[].shares: number · required
data.videos[].comments: number · required
data.videos[].bookmarks: number | null · optional
data.videos[].publish_date: string | null · optional
data.videos[].duration: number | null · optional
data.videos[].author: object | null · optional
data.videos[].hashtags: array · optional
data.videos[].thumbnail_url: string | null · optional
data.videos[].keyword_found_by: string | null · optional
data.videos[].is_duet: boolean | null · optional
data.videos[].is_stitch: boolean | null · optional
data.videos[].is_paid: boolean · optional
data.videos[].paid_signals: array · optional
data.videos[].upload_region: string | null · optional
data.videos[].upload_region_source: string | null · optional
data.videos[].intelligence: object | null · optional
data.videos[].intelligence_status: string · optional · values: ready, pending, disabled, failed, skipped
data.videos[].intelligence_skip_reason: string | null · optional · values: intent_mismatch, too_old, under_followers
data.videos[].intent_match: object | null · optional
data.videos[].sound: object | null · optional
data.videos[].transcript: object | null · optional

Documented HTTP responses: 200, 401, 404, 429. Handle each non-success response explicitly; do not silently convert a failed lookup to an empty result.

Before you integrate

An intent-matched collection is a selected research sample, not a neutral ranking of all videos.

Check the provider's current price, allowed use and retention terms before sending requests. An optional field can be absent; the schema alone does not establish its completeness or accuracy.

Give this task to your coding agent

social-video-research-api agent prompt

Help me implement social video research api using the documented Virlo API.

Reference: https://allthemapis.com/social-media-apis/social-video-research-api
Provider documentation: https://dev.virlo.ai/docs/agents
Base URL: https://api.virlo.ai
Starting operation: GET /v1/agents/{id}/videos

Read the current provider docs and confirm the required inputs before writing code. Load VIRLO_API_KEY from a server-side environment variable and use Bearer authentication. Do not put the key in client code, logs, analytics, or the chat.

Ask me for any missing video URL, creator handle, research intent, or job ID. Do not invent a result. Ask for approval before starting billable lookups, recurring jobs, or destructive changes. For jobs, keep the returned ID and poll with the documented delay instead of starting the job twice. Handle pagination, rate limits, partial results, and missing fields explicitly.

Build the smallest integration for this task:
1. Create a research agent with a specific topic and platform scope.
2. Read the finished run before paging through its videos.
3. Keep the agent and run IDs with each video so the selection can be explained later.

Return the code, the environment variables I need, and a short explanation of what was actually retrieved versus inferred. Do not execute paid requests until I approve.

Sources and review dates

Virlo's public documentation and OpenAPI schema reviewed October 27, 2026. Endpoint paths and field names below refer to that provider's API. This is an integration reference, not a measured performance ranking.

Corrections: email faizank@docsalot.dev with an official source.