Orbit

Get keyword search status and results

Polls the status of a keyword search job and retrieves results once complete.

get/v1/orbit/{orbit_id}

Request

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

Path parameters

orbit_idstring required

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

Query parameters

order_by'views' | 'likes' | 'shares' | 'comments' | 'bookmarks' | 'publish_date' | 'author.followers'
Example:views

Field to sort videos by

sort'asc' | 'desc'
Example:desc

Sort direction

Response

Successfully retrieved search results

Example response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "pending_jobs": [
      {
        "type": "viral_analysis",
        "status": "processing",
        "job_id": "aud_01HXYZ",
        "poll_url": "/v1/orbit/orb_01HXYZ/analysis/latest",
        "result_path": "data.analysis_data",
        "webhook_event": "orbit.run.completed",
        "started_at": "2026-05-22T05:00:00.000Z",
        "retry_after_seconds": 15
      }
    ],
    "name": "My keyword search",
    "keywords": [
      "fitness",
      "workout"
    ],
    "analysis_batch_start": "2026-04-14T00:00:00.000Z",
    "analysis_batch_end": "2026-04-21T00:00:00.000Z",
    "started_at": "2026-01-15T10:30:00.000Z",
    "order_by": "views",
    "sort": "desc",
    "results": {
      "total_videos": 150,
      "total_slideshows": 210,
      "youtube_count": 50,
      "tiktok_count": 80,
      "instagram_count": 20,
      "trends": [
        {
          "name": "AI-powered fitness coaching",
          "description": "Creators using AI tools for personalized plans",
          "videoCount": 12,
          "confidence": 0.85
        }
      ],
      "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"
        }
      ],
      "slideshows": [
        {
          "url": "https://www.tiktok.com/@user/photo/123",
          "platform": "tiktok",
          "views": 250000,
          "likes": 12000,
          "shares": 500,
          "comments": 340,
          "bookmarks": 1200,
          "publish_date": "2026-01-15T10:30:00.000Z",
          "hashtags": [
            "fyp",
            "viral"
          ],
          "images": [
            {
              "image_url": "https://storage.example.com/slideshow-images/abc.webp"
            }
          ],
          "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",
          "region": "US",
          "intelligence_status": "pending"
        }
      ],
      "ads": [
        {
          "id": 1234,
          "ad_archive_id": "987654321",
          "page_id": "111222333",
          "is_active": true,
          "start_date": "2026-01-01T00:00:00.000Z",
          "end_date": "2026-02-01T00:00:00.000Z",
          "url": "https://example.com/ad",
          "cta_type": "SHOP_NOW",
          "page_like_count": 50000,
          "created_at": "2026-01-15T10:30:00.000Z"
        }
      ],
      "execution_time_ms": 45000,
      "keyword_breakdown": [
        {
          "keyword": "matcha routine",
          "video_count": 42
        }
      ]
    }
  }
}

Changes

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