Videos

Top-performing videos published in the last ~48 hours. Each digest request costs $0.25.

Platform	Endpoint
Cross-platform	`GET /v1/videos/digest`
YouTube	`GET /v1/youtube/videos/digest`
TikTok	`GET /v1/tiktok/videos/digest`
Instagram	`GET /v1/instagram/videos/digest`

Get videos digest

Returns the top videos published in the last 48 hours, ordered by view count (highest first).

Cost per request:$0.25

Query parameters

Name
limit
Type
number
Description
Number of top videos to return (1-100). Default is 50.

Response fields

Each item in the data array describes one video. Key fields include:

Name
id
Type
string
Description
Virlo's internal UUID for the video.
Name
url
Type
string
Description
Canonical URL of the video on its platform.
Name
publish_date
Type
string
Description
When the video was published (ISO-8601).
Name
views
Type
integer | null
Description
View count. null when the platform hasn't reported it yet.
Name
number_of_likes
Type
integer
Description
Like count.
Name
number_of_shares
Type
integer
Description
Share count.
Name
number_of_comments
Type
integer
Description
Comment count.
Name
bookmarks
Type
integer
Description
Bookmark / save count.
Name
description
Type
string
Description
Caption / description text.
Name
thumbnail_url
Type
string
Description
Full URL to the video thumbnail.
Name
hashtags
Type
string[] | null
Description
Array of hashtag strings, or null when none are present.
Name
type
Type
string
Description
Source platform: youtube, tiktok, or instagram.
Name
niche
Type
string
Description
Virlo niche the video was classified into.
Name
author_id
Type
string | null
Description
Virlo UUID of the author, when known.
Name
external_id
Type
string
Description
Platform-native video ID.
Name
region
Type
string | null
Description
Two-letter region/country code, when available. Currently always identical to upload_region — prefer upload_region, which is the field the rest of the API uses.
Name
upload_region
Type
string | null
Description
The uploader's country as an ISO-3166-1 alpha-2 code (e.g. US, CA, CH), or null when it couldn't be resolved. Same field and semantics as on agent videos.
Name
upload_region_source
Type
string | null
Description
How upload_region was resolved — tiktok_region, youtube_channel_country, and instagram_location_tag are platform-provided and exact; inferred_normalize is directional. null when unresolved.
Name
duration
Type
integer | null
Description
Video length in seconds, when available.
Name
transcript_raw
Type
string | null
Description
Raw transcript text, when available.
Name
is_eligible_for_commission
Type
boolean | null
Description
Whether the video is eligible for commission (e.g. TikTok Shop), when known.
Name
is_duet
Type
boolean | null
Description
TikTok only — whether the video is a duet. null on other platforms or when unknown.
Name
is_stitch
Type
boolean | null
Description
TikTok only — whether the video is a stitch. null on other platforms or when unknown.
Name
sound
Type
object | null
Description
The video's sound metadata — { id, title, platform, duration, cover_url, owner_handle, owner_nickname, is_original, is_commerce_music, usage_count }. null on roughly 80% of digest rows, since sound is only attached where the platform exposed it and Virlo has already indexed that sound. Always null-check before reading. Use sound.id with GET /v1/sounds/:sound_id to pull full details.

The list above covers the key fields; the response may include additional internal fields. Nullable fields (views, hashtags, author_id, region, duration, transcript_raw, is_eligible_for_commission, is_duet, is_stitch, sound) are null when the platform hasn't supplied the value.

Request

GET

/v1/videos/digest

curl -G https://api.virlo.ai/v1/videos/digest \
  -H "Authorization: Bearer {token}" \
  -d limit=50

Response

{
  "data": [
    {
      "id": "e30b40b1-15fa-4d00-8db3-3eb83e94546d",
      "url": "https://www.youtube.com/watch?v=dkCFBauD2F4",
      "publish_date": "2025-10-22T04:00:51",
      "views": 11166267,
      "number_of_likes": 36859,
      "number_of_shares": 402,
      "number_of_comments": 23,
      "description": "Noah's amazing toy unboxing ASMR video experience #toys #asmr  #satisfying  #unboxing",
      "thumbnail_url": "https://auth.virlo.ai/storage/v1/object/public/thumbnails/6c72771e-a3af-43c0-8951-605474eab5ec.jpg",
      "hashtags": ["#toys", "#asmr", "#satisfying", "#unboxing"],
      "type": "youtube",
      "niche": "asmr",
      "author_id": "b466d69a-cb59-44db-a59f-0f60039a18e8",
      "bookmarks": 0,
      "external_id": "dkCFBauD2F4",
      "region": null,
      "upload_region": null,
      "upload_region_source": null,
      "duration": 8,
      "transcript_raw": null,
      "is_eligible_for_commission": null,
      "is_duet": null,
      "is_stitch": null,
      "sound": null
    },
    {
      "id": "65e6604e-7469-4c6c-aa49-cb93b6feac36",
      "url": "https://www.tiktok.com/@dailymail/video/7564023786111028535",
      "publish_date": "2025-10-22T13:00:00",
      "views": 10439698,
      "number_of_likes": 865067,
      "number_of_shares": 18420,
      "number_of_comments": 12065,
      "description": "She did their job for them 😳 🎥 Newsflare #trash #news #usa #mom",
      "thumbnail_url": "https://auth.virlo.ai/storage/v1/object/public/thumbnails/8dfc5b77-72aa-4965-baac-e6627c308ad9.jpg",
      "hashtags": null,
      "type": "tiktok",
      "niche": "breaking-news",
      "author_id": "16244f6f-4d83-44b2-a627-612f700065ea",
      "bookmarks": 22108,
      "external_id": "7564023786111028535",
      "region": "US",
      "upload_region": "US",
      "upload_region_source": "tiktok_region",
      "duration": 65,
      "transcript_raw": "She did their job for them...",
      "is_eligible_for_commission": false,
      "is_duet": false,
      "is_stitch": false,
      "sound": {
        "id": "8f6e5c50-1451-4007-a120-92744e632dad",
        "title": "original sound - dailymail",
        "platform": "tiktok"
      }
    }
  ]
}

Error responses

The videos digest endpoint may return the following error codes:

Name
400 Bad Request
Description
Invalid parameters provided. Common causes include: - Invalid limit value (must be 1-100)
Name
401 Unauthorized
Description
Missing or invalid API key. Ensure you're including your API key in the Authorization header.
Name
402 Payment Required
Description
Insufficient prepaid balance. Add funds at dev.virlo.ai/dashboard/billing.
Name
429 Too Many Requests
Description
Rate limit exceeded. Your plan has specific rate limits per endpoint. Wait before making additional requests.