Orbit

Get videos for a keyword search

Retrieves videos linked to a keyword search with filtering, pagination, and sorting.

get/v1/orbit/{orbit_id}/videos

Request

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

Path parameters

orbit_idstring required

Orbit search ID (UUID) returned when the search was created.

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:10000

Minimum view count filter

platformsstring[]

Filter by platform(s)

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

Filter videos published after this date (ISO date string)

end_datestring
Example:2024-12-31T23:59:59Z

Filter videos published before this date (ISO date string)

order_by'publish_date' | 'views' | 'created_at'
Example:publish_date

Field to sort by

sort'asc' | 'desc'
Example:desc

Sort direction

intent_matchboolean

Filter videos by intent match result. Only applies when the search used intent + data_intelligence_enabled. Pass true to get only matching videos, false for non-matching.

Response

Successfully retrieved videos

Example response

{
  "data": {
    "orbit_id": "550e8400-e29b-41d4-a716-446655440000",
    "total": 150,
    "limit": 50,
    "videos": [
      {
        "url": "https://www.tiktok.com/@user/video/123",
        "platform": "tiktok",
        "views": 250000,
        "likes": 12000,
        "shares": 500,
        "comments": 340,
        "bookmarks": 1200,
        "publish_date": "2026-01-15T10:30:00.000Z",
        "hashtags": [
          "fyp",
          "viral"
        ],
        "author": {
          "username": "creator_handle",
          "avatar_url": "https://auth.virlo.ai/storage/v1/object/public/avatars/abc.jpg",
          "followers": 160726,
          "country": "US"
        },
        "keyword_found_by": "fitness tips",
        "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
        },
        "intelligence_status": "pending"
      }
    ]
  }
}

Changes

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