Orbit - Social Listening

The Orbit endpoint suite enables deep social listening research by analyzing viral videos across YouTube, TikTok, and Instagram based on your keywords. Queue asynchronous analysis jobs, poll for results, and retrieve comprehensive insights about the short-form social media landscape including paginated videos, Meta ads, and creator outlier detection. Queuing a search costs $0.50 per job (deducted from your prepaid balance); polling and result retrieval are free unless noted.

All Orbit V1 endpoints use the base URL https://api.virlo.ai/v1/orbit. Request parameters use snake_case. All responses are wrapped in a { "data": { ... } } envelope. The orbit list endpoint returns summary fields in camelCase (totalVideos, createdAt, executionTimeMs) for legacy compatibility; all other responses use snake_case.

POST/v1/orbit

Queue keyword search

Queues a new keyword-based video discovery job that searches across YouTube, TikTok, and/or Instagram. This endpoint returns immediately with an orbit_id that you can use to poll for results. Perfect for niche research, trend discovery, and competitive analysis.

Cost per search:

Request body

Name
name
Type
string
Required
*
Description
A descriptive name for this search job. Example: "NYC Mayoral Race Social Listening" or "Q4 Campaign Monitoring"
Name
keywords
Type
string[]
Required
*
Description
Array of keywords to search for (1-10 keywords). Example: ["NYC mayor election 2025", "NYC mayoral candidates", "Eric Adams"]
Pro tip: Avoid generic single words like "jets" or "legends" — they return unrelated content. Use specific keyword phrases like "new york jets" or "apex legends" for accurate, targeted results. Keyword sets (multi-word phrases) dramatically improve search quality.
Name
time_period
Type
string
Required
*
Description
Time period filter for video publish date. Options: today, this_week, this_month, this_year.
Name
platforms
Type
string[]
Description
Platforms to analyze. Options: youtube, tiktok, instagram. Defaults to all platforms if not specified.
Name
min_views
Type
integer
Description
Minimum view count threshold for videos. Filters out videos below this threshold. Default: 0. Example: 30000
Name
run_analysis
Type
boolean
Description
Deprecated — analysis is now always generated for every Orbit (free, included with the $0.50 search cost). The parameter is still accepted for backwards compatibility but has no effect: the structured AI analysis and trends are available via GET /v1/orbit/:orbit_id/analysis/latest and GET /v1/orbit/:orbit_id/trends/latest as soon as the job completes. Default: false
Name
enable_meta_ads
Type
boolean
Description
Enable Meta ads collection for this search. When enabled, the system will collect Meta ads related to your keywords. Default: false
Name
exclude_keywords
Type
string[]
Description
Keywords to exclude from video results. Videos containing these keywords in their title will be filtered out. Example: ["spam", "clickbait"]
Name
exclude_keywords_strict
Type
boolean
Description
If true, also check video transcript for exclude_keywords matching. Default: false. Only checks titles when false.
Name
intent
Type
string
Description
Intent or purpose for this search. Use it to describe the goal behind the search job. When combined with data_intelligence_enabled: true, the intent triggers a post-intelligence evaluation step: after the 40+ structured intelligence fields are populated, each video is evaluated against your intent and receives an intent_match result. Example: "Find viral brainrot content for trend analysis"
Name
data_intelligence_enabled
Type
boolean
Description
Enable per-video AI intelligence. When true, each video receives 40+ structured fields including topics, hooks, emotional tone, brand safety, visual format, CTAs, and more. Adds +$1.00 to the base $0.50 search cost ($1.50 total). See Data Intelligence for the full field reference. Default: false

Request

POST

/v1/orbit

curl -X POST https://api.virlo.ai/v1/orbit \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "NYC Mayoral Race Social Listening",
    "keywords": ["NYC mayor election 2025", "Eric Adams", "Scott Stringer"],
    "platforms": ["youtube", "tiktok"],
    "min_views": 10000,
    "time_period": "this_week",
    "enable_meta_ads": false,
    "exclude_keywords": ["spam", "irrelevant"],
    "exclude_keywords_strict": false,
    "intent": "Track social media sentiment around NYC mayoral race"
  }'

Response

{
  "data": {
    "orbit_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "queued",
    "message": "Keyword search job queued with max priority."
  }
}

GET/v1/orbit

List searches

Retrieve a paginated list of all keyword search jobs for the authenticated customer. Returns summaries of each search including status, keywords used, platforms analyzed, and total videos found.

Cost per request:

Free

Query parameters

Name
limit
Type
integer
Description
Maximum number of results to return (1-100). Default is 50.
Name
page
Type
integer
Description
Page number (1-indexed). Default is 1.

Request

GET

/v1/orbit

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

Response

{
  "data": {
    "total": 47,
    "limit": 50,
    "offset": 0,
    "orbits": [
      {
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "name": "NYC Mayoral Race Social Listening",
        "keywords": ["NYC mayor election 2025", "Eric Adams"],
        "platforms": ["youtube", "tiktok"],
        "status": "completed",
        "totalVideos": 347,
        "createdAt": "2025-01-15T10:30:00.000Z",
        "executionTimeMs": 487392
      },
      {
        "id": "a12bc34d-56ef-7890-g123-h456i789j012",
        "name": "Gaming Industry Research",
        "keywords": ["gaming reviews", "esports"],
        "platforms": ["youtube", "tiktok"],
        "status": "processing",
        "totalVideos": 0,
        "createdAt": "2025-01-15T02:15:00.000Z",
        "executionTimeMs": 0
      }
    ]
  }
}

GET/v1/orbit/:orbit_id

Get search results

Retrieves the status and full results of a keyword analysis job. Use the orbit_id returned from the POST endpoint. While the job is processing, this returns a status update. Once complete, it returns comprehensive results including videos, trends, platform breakdowns, usage/cost metadata (via response headers), and optionally a Virlo social intelligence report.

Cost per request:(polling is always free)

Important: The analysis field now always surfaces a short one-sentence summary of what drove engagement for this Orbit, regardless of whether run_analysis was passed (the flag is kept for backwards compatibility only — see the deprecation note on run_analysis). For the full structured analysis and trends with evidence videos and aggregate stats, use GET /v1/orbit/:orbit_id/analysis/latest and GET /v1/orbit/:orbit_id/trends/latest.

Path parameters

Name
orbit_id
Type
string
Required
*
Description
The unique identifier returned when queuing the search job.

Query parameters

Name
order_by
Type
string
Description
Field to sort videos by. Options: views, likes, shares, comments, bookmarks, publish_date, author.followers.
Name
sort
Type
string
Description
Sort direction: asc or desc. Default is desc.

Response fields

Name
analysis
Type
string
Description
Short one-sentence narrative summary of what drove engagement for this Orbit's video set. Present whenever the search is completed. For the full structured analysis (themes, viral tactics, timing analysis, overview) use GET /v1/orbit/:orbit_id/analysis/latest.
Name
analysis_data
Type
object
Description
Full structured analysis object. Includes themes (the distinct trends surfaced in this batch), viral_tactics, timing_analysis, and overview. Present whenever the search is completed. For a flat, paginated projection of the same themes (with aggregate stats and evidence videos) use GET /v1/orbit/:orbit_id/trends/latest.
Name
analysis_batch_start
Type
string
Description
ISO 8601 timestamp marking the start of the batch window analyzed.
Name
analysis_batch_end
Type
string
Description
ISO 8601 timestamp marking the end of the batch window analyzed.
Name
name
Type
string
Description
The descriptive name you provided when creating this search job.
Name
keywords
Type
string[]
Description
The array of keywords used for this search.
Name
intent
Type
string
Description
The intent or purpose provided when creating this search job.
Name
intent_summary
Type
object
Description
Aggregate intent-match statistics for this run. Contains matched (number of videos matching the intent), total_evaluated, not_evaluated, and matched_urls. Present when the run used both intent and data_intelligence_enabled: true; null otherwise. See Intent Matching.
Name
results
Type
object
Description
Contains total_videos, total_slideshows, youtube_count, tiktok_count, instagram_count, trends, videos, slideshows, ads, and creators (with outliers). Will be null while the search is still processing.

Request

GET

/v1/orbit/:orbit_id

curl -G https://api.virlo.ai/v1/orbit/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "Authorization: Bearer {token}" \
  -d order_by=views \
  -d sort=desc

Response

{
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "processing",
    "started_at": "2025-01-15T10:30:00.000Z",
    "name": "NYC Mayoral Race Social Listening",
    "keywords": ["NYC mayor election 2025", "Eric Adams", "Scott Stringer"],
    "intent": "Track social media sentiment around NYC mayoral race",
    "results": null
  }
}

GET/v1/orbit/:orbit_id/videos

Get videos

Get paginated videos for a completed keyword search. Use this endpoint to browse through large result sets with filtering and sorting. This is the recommended way to access video results for searches with many results.

Cost per request:

Path parameters

Name
orbit_id
Type
string
Required
*
Description
The unique identifier of the keyword search.

Query parameters

Name
limit
Type
integer
Description
Maximum number of results to return (1-100). Default is 50.
Name
page
Type
integer
Description
Page number (1-indexed). Default is 1.
Name
min_views
Type
integer
Description
Minimum view count filter. Only return videos with at least this many views.
Name
platforms
Type
string
Description
Comma-separated list of platforms to filter by. Example: youtube,tiktok
Name
start_date
Type
string
Description
Earliest publish date filter (ISO 8601). Example: 2025-01-01T00:00:00.000Z
Name
end_date
Type
string
Description
Latest publish date filter (ISO 8601). Example: 2025-01-31T23:59:59.000Z
Name
order_by
Type
string
Description
Field to sort by. Options: publish_date, views, created_at. Default is publish_date.
Name
sort
Type
string
Description
Sort direction: asc or desc. Default is desc.
Name
intent_match
Type
string
Description
Filter videos by intent match result. Set to true to return only videos that matched the intent, or false for non-matches. Requires the run to have used both intent and data_intelligence_enabled: true. Omit to return all videos regardless of match status.

Request

GET

/v1/orbit/:orbit_id/videos

curl -G https://api.virlo.ai/v1/orbit/f47ac10b-58cc-4372-a567-0e02b2c3d479/videos \
  -H "Authorization: Bearer {token}" \
  -d limit=50 \
  -d page=1 \
  -d min_views=10000 \
  -d platforms=youtube,tiktok \
  -d order_by=views \
  -d sort=desc

Response

{
  "data": {
    "orbit_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "orbit_name": "NYC Mayoral Race Social Listening",
    "total": 142,
    "limit": 50,
    "offset": 0,
    "videos": [
      {
        "id": "ece460f3-fad8-4fc5-bdcd-5530498ac28c",
        "url": "https://youtube.com/watch?v=abc123",
        "description": "Everything you need to know about the 2025 NYC mayoral race...",
        "platform": "youtube",
        "views": 500000,
        "likes": 12000,
        "shares": null,
        "comments": 890,
        "bookmarks": 0,
        "publish_date": "2025-01-15T00:00:00.000Z",
        "author": {
          "username": "creator_name",
          "verified": true,
          "followers": 150000,
          "avatar_url": "https://example.com/avatar.jpg"
        },
        "hashtags": ["#siberianhusky", "#huskydog"],
        "thumbnail_url": "21312058-a829-4cc6-88b0-308db517dc83.jpg",
        "keyword_found_by": "NYC mayor election 2025",
        "intent_match": {
          "matches": true,
          "reasoning": "Video covers NYC mayoral race sentiment with political commentary (primary_topic: politics, sentiment: negative), matching the intent to track social media sentiment."
        }
      }
    ]
  }
}

GET/v1/orbit/:orbit_id/slideshows

Get slideshows

Get paginated slideshows (image carousels) for a completed keyword search. Accepts the same query parameters as the videos endpoint. Use this endpoint to browse through slideshow results with filtering and sorting.

Cost per request:

Path parameters

Name
orbit_id
Type
string
Required
*
Description
The unique identifier of the keyword search.

Query parameters

Name
limit
Type
integer
Description
Maximum number of results to return (1-100). Default is 50.
Name
page
Type
integer
Description
Page number (1-indexed). Default is 1.
Name
min_views
Type
integer
Description
Minimum view count filter. Only return slideshows with at least this many views.
Name
start_date
Type
string
Description
Earliest publish date filter (ISO 8601). Example: 2025-01-01T00:00:00.000Z
Name
end_date
Type
string
Description
Latest publish date filter (ISO 8601). Example: 2025-01-31T23:59:59.000Z
Name
order_by
Type
string
Description
Field to sort by. Options: publish_date, views, created_at. Default is publish_date.
Name
sort
Type
string
Description
Sort direction: asc or desc. Default is desc.

Request

GET

/v1/orbit/:orbit_id/slideshows

curl -G https://api.virlo.ai/v1/orbit/f47ac10b-58cc-4372-a567-0e02b2c3d479/slideshows \
  -H "Authorization: Bearer {token}" \
  -d limit=50 \
  -d page=1 \
  -d min_views=10000 \
  -d order_by=views \
  -d sort=desc

Response

{
  "data": {
    "orbit_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "orbit_name": "Celebs",
    "total": 210,
    "limit": 50,
    "offset": 0,
    "slideshows": [
      {
        "url": "https://www.tiktok.com/@user/photo/123",
        "description": "Hold me backkkkk #fy #viral",
        "platform": "tiktok",
        "views": 223780,
        "likes": 21417,
        "shares": 2997,
        "comments": 70,
        "bookmarks": 2907,
        "publish_date": "2026-04-10T16:02:19+00:00",
        "hashtags": ["fy", "viral"],
        "thumbnail_url": "https://example.com/thumb.jpg",
        "images": [
          { "image_url": "https://example.com/abc.webp", "position": 0 },
          { "image_url": "https://example.com/def.webp", "position": 1 }
        ],
        "author": {
          "username": "pixcarpenter69",
          "verified": false,
          "followers": 1510,
          "avatar_url": "https://example.com/avatar.jpg"
        },
        "keyword_found_by": "Sabrina Carpenter",
        "is_eligible_for_commission": false,
        "region": "DE",
        "intelligence_status": "ready",
        "intelligence": {
          "primary_topic": "Sabrina Carpenter concert outfit recap",
          "category": "entertainment",
          "content_format": "photo_recap",
          "narrative_arc": "buildup_to_reveal",
          "text_density": "moderate",
          "panel_texts": ["Concert outfit 1", "Concert outfit 2"],
          "image_count": 2,
          "brand_safety_tier": "safe"
        }
      }
    ]
  }
}

Slideshow items carry the same intelligence_status flag as video items (ready · pending · disabled · failed · skipped) when the parent orbit was queued with data_intelligence_enabled: true. The intelligence payload shape is different from videos — slideshows analyse the per-panel text (panel_texts, panel_text_word_count, narrative_arc, text_density, image_count) instead of a transcript, and drop video-only fields like visual_format, camera_perspective, and scene_changed. See the Data Intelligence reference for the full slideshow schema.

GET/v1/orbit/:orbit_id/ads

Get ads

Get paginated Meta ads collected during a keyword search. Only returns results if enable_meta_ads: true was set when the search was queued. Use this endpoint to browse through ad creatives, landing pages, and ad performance data.

Cost per request:

Path parameters

Name
orbit_id
Type
string
Required
*
Description
The unique identifier of the keyword search.

Query parameters

Name
limit
Type
integer
Description
Maximum number of results to return (1-100). Default is 50.
Name
page
Type
integer
Description
Page number (1-indexed). Default is 1.
Name
order_by
Type
string
Description
Field to sort by. Options: created_at, page_like_count. Default is created_at.
Name
sort
Type
string
Description
Sort direction: asc or desc. Default is desc.

Request

GET

/v1/orbit/:orbit_id/ads

curl -G https://api.virlo.ai/v1/orbit/f47ac10b-58cc-4372-a567-0e02b2c3d479/ads \
  -H "Authorization: Bearer {token}" \
  -d limit=50 \
  -d page=1 \
  -d order_by=page_like_count \
  -d sort=desc

Response

{
  "data": {
    "orbit_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "orbit_name": "NYC Mayoral Race Social Listening",
    "total": 28,
    "limit": 50,
    "offset": 0,
    "ads": [
      {
        "id": "5f9d1551-2cd4-441d-bb36-c150fbcc27c7",
        "ad_archive_id": "4362525100698401",
        "page_id": "101720278791083",
        "page_profile_url": "https://www.facebook.com/PageName/",
        "page_profile_picture_url": "https://example.com/page-avatar.jpg",
        "is_active": true,
        "start_date": "2025-01-10",
        "end_date": "2025-02-10",
        "url": "https://www.facebook.com/ads/library?id=4362525100698401",
        "caption": "example.com",
        "body": "Our plan to make NYC safer, cleaner, and more affordable starts with your support.",
        "cta_type": "SHOP_NOW",
        "page_like_count": 45000,
        "title": "A New Vision for NYC",
        "video_url": "https://example.com/ad-video.mp4",
        "created_at": "2025-01-12T00:00:00.000Z",
        "keyword_found_by": "NYC mayor election 2025"
      }
    ]
  }
}

GET/v1/orbit/:orbit_id/creators/outliers

Get creator outliers

Get creators who significantly outperform their follower count. Outliers are identified by comparing a creator's average views to their follower count — a high outlier_ratio means the creator's content consistently reaches far beyond their follower base. Each outlier may also include an optional weighted_score (Virality Score), a size-weighted metric you can sort with order_by=weighted_score. Each outlier includes the specific videos that contributed to the detection. This is invaluable for finding rising creators, potential brand partners, and undiscovered talent.

Cost per request:

Path parameters

Name
orbit_id
Type
string
Required
*
Description
The unique identifier of the keyword search.

Query parameters

Name
limit
Type
integer
Description
Maximum number of results to return (1-100). Default is 50.
Name
page
Type
integer
Description
Page number (1-indexed). Default is 1.
Name
order_by
Type
string
Description
Field to sort by. Options: outlier_ratio, avg_views, follower_count, weighted_score. Default is outlier_ratio.
Name
sort
Type
string
Description
Sort direction: asc or desc. Default is desc.
Name
platform
Type
string
Description
Filter by platform. Options: youtube, tiktok, instagram.

Request

GET

/v1/orbit/:orbit_id/creators/outliers

curl -G https://api.virlo.ai/v1/orbit/f47ac10b-58cc-4372-a567-0e02b2c3d479/creators/outliers \
  -H "Authorization: Bearer {token}" \
  -d limit=50 \
  -d page=1 \
  -d order_by=outlier_ratio \
  -d sort=desc \
  -d platform=youtube

Response

{
  "data": {
    "orbit_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "orbit_name": "NYC Mayoral Race Social Listening",
    "total": 25,
    "limit": 50,
    "offset": 0,
    "hasMore": false,
    "outliers": [
      {
        "creator_url": "https://youtube.com/@tech_creator",
        "creator_avatar_url": "https://yt3.googleusercontent.com/example-tech-creator-avatar",
        "follower_count": 50000,
        "avg_views": 2500000,
        "outlier_ratio": 50.0,
        "weighted_score": 26.9,
        "videos_analyzed": 12,
        "creator_topics": ["tech reviews", "gadgets"],
        "matching_topics": ["tech reviews"],
        "platform": "youtube",
        "identified_at": "2025-01-15T10:30:00.000Z",
        "videos": [
          {
            "id": "7606705096256261406",
            "title": "This $50 Gadget Changed Everything",
            "description": "I found the most underrated tech product of 2025...",
            "views": 5200000,
            "likes": 180000,
            "comments": 12000,
            "publish_date": "2025-01-10T14:00:00.000Z",
            "hashtags": ["tech", "gadgets", "review"]
          }
        ]
      },
      {
        "creator_url": "https://tiktok.com/@rising_star",
        "creator_avatar_url": "https://p16-sign-sg.tiktokcdn.com/example-rising-star-avatar",
        "follower_count": 12000,
        "avg_views": 360000,
        "outlier_ratio": 30.0,
        "videos_analyzed": 8,
        "creator_topics": ["politics", "NYC life"],
        "matching_topics": ["politics"],
        "platform": "tiktok",
        "identified_at": "2025-01-15T10:30:00.000Z",
        "videos": [
          {
            "id": "7318456789012345678",
            "title": "",
            "description": "NYC mayor needs to see this #nyc #politics",
            "views": 890000,
            "likes": 45000,
            "comments": 3200,
            "publish_date": "2025-01-13T18:20:00.000Z",
            "hashtags": ["nyc", "politics", "nycmayor"]
          }
        ]
      }
    ]
  }
}

GET/v1/orbit/:orbit_id/analysis

Query orbit analyses

Returns the analysis record(s) associated with this Orbit, paginated and ordered newest first. Orbits are single-shot collections (as opposed to Comets, which run on a cadence), so this endpoint typically returns a single record — it exists for API symmetry with Comet and to keep client code uniform across both resources.

Cost per request:Free(included with the Orbit search)

Path parameters

Name
orbit_id
Type
string
Required
*
Description
UUID of the Orbit job.

Query parameters

Name
page
Type
integer
Description
Page number for pagination (1-indexed). Default is 1.
Name
limit
Type
integer
Description
Maximum number of analyses to return (1-100). Default is 20.
Name
start_date
Type
string
Description
ISO 8601 date to filter analyses from (inclusive).
Name
end_date
Type
string
Description
ISO 8601 date to filter analyses until (inclusive).

Request

GET

/v1/orbit/:orbit_id/analysis

curl -G https://api.virlo.ai/v1/orbit/f47ac10b-58cc-4372-a567-0e02b2c3d479/analysis \
  -H "Authorization: Bearer {token}" \
  -d page=1 \
  -d limit=20

Response

{
  "data": [
    {
      "id": "0589e73f-114b-4e2c-bda9-787d843fb1f7",
      "insight_type": "orbit",
      "reference_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "batch_start": "2025-01-15T10:30:00.000Z",
      "batch_end": "2025-01-15T10:39:55.000Z",
      "analysis": "Eric Adams criticism surged...",
      "analysis_data": { "themes": ["..."] }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "has_more": false
  }
}

GET/v1/orbit/:orbit_id/analysis/latest

Get latest orbit analysis

Returns the AI-generated social intelligence analysis for this Orbit. Each Orbit produces exactly one analysis record once the search is completed; it is based on the videos collected for that job.

Cost per request:Free(included with the Orbit search)

Path parameters

Name
orbit_id
Type
string
Required
*
Description
UUID of the Orbit job.

Response fields

Name
id
Type
string
Description
UUID of the analysis record.
Name
insight_type
Type
string
Description
Always "orbit" for Orbit analyses.
Name
reference_id
Type
string
Description
UUID of the Orbit job this analysis belongs to.
Name
batch_start
Type
string
Description
ISO 8601 timestamp marking when the Orbit began collecting videos.
Name
batch_end
Type
string
Description
ISO 8601 timestamp marking when the Orbit completed.
Name
analysis
Type
string
Description
Short one-sentence narrative summary.
Name
analysis_data
Type
object
Description
Full structured analysis with themes, viral_tactics, timing_analysis, and overview. See Query orbit trends for a paginated projection of the themes with aggregate stats.

Request

GET

/v1/orbit/:orbit_id/analysis/latest

curl https://api.virlo.ai/v1/orbit/f47ac10b-58cc-4372-a567-0e02b2c3d479/analysis/latest \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "id": "0589e73f-114b-4e2c-bda9-787d843fb1f7",
    "insight_type": "orbit",
    "reference_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "batch_start": "2025-01-15T10:30:00.000Z",
    "batch_end": "2025-01-15T10:39:55.000Z",
    "analysis": "Eric Adams criticism surged across TikTok (52% of content)...",
    "analysis_data": {
      "themes": [
        {
          "stable_key": "subway-crime-compilations",
          "name": "Subway crime compilations",
          "why_it_works": "Short, visceral clips tap into shared daily commuter frustration.",
          "video_count": 48,
          "evidence_video_ids": ["..."],
          "tactics": ["shock-cut opener", "voiceover with sarcasm"],
          "confidence": 0.91
        }
      ],
      "viral_tactics": ["..."],
      "timing_analysis": { "peak_hours": [19, 21] },
      "overview": { "total_videos": 347 }
    }
  }
}

GET/v1/orbit/:orbit_id/trends

Query orbit trends

Returns the trend records associated with this Orbit, paginated and ordered newest first. Use stable_key to filter for a specific trend, or start_date/end_date to window the results. Since Orbits are single-shot collections, this endpoint typically returns a single batch of trends — it exists for API symmetry with Comet and supports filtering so you can keep uniform client code across both resources.

Cost per request:Free

Path parameters

Name
orbit_id
Type
string
Required
*
Description
UUID of the Orbit job.

Query parameters

Name
page
Type
integer
Description
Page number for pagination (1-indexed). Default is 1.
Name
limit
Type
integer
Description
Maximum number of trend records to return (1-100). Default is 50.
Name
stable_key
Type
string
Description
Filter to return only trend records matching a specific stable_key.
Name
start_date
Type
string
Description
ISO 8601 date to filter trends from (inclusive).
Name
end_date
Type
string
Description
ISO 8601 date to filter trends until (inclusive).

Response fields (per trend)

Name
rank
Type
integer
Description
1-based rank within this batch (lower = more prominent).
Name
stable_key
Type
string
Description
Slug-like identifier reused by the LLM across comparable batches.
Name
name
Type
string
Description
Human-readable name of the trend.
Name
why_it_works
Type
string
Description
Short explanation of why this trend drives engagement.
Name
tactics
Type
string[]
Description
Concrete execution tactics creators use for this trend.
Name
confidence
Type
number
Description
LLM confidence that this is a genuinely distinct trend (0-1).
Name
evidence_video_ids
Type
string[]
Description
UUIDs of the videos that constitute evidence for this trend.
Name
video_count
Type
integer
Description
Number of videos in this trend.
Name
total_views
Type
integer
Description
Aggregate views across evidence videos.
Name
total_likes
Type
integer
Description
Aggregate likes across evidence videos.
Name
total_comments
Type
integer
Description
Aggregate comments across evidence videos.
Name
total_shares
Type
integer
Description
Aggregate shares across evidence videos.
Name
avg_virality_score
Type
number
Description
Average Virlo virality score across evidence videos.
Name
platform_breakdown
Type
object
Description
Map of platform → count of evidence videos.
Name
top_creators
Type
object[]
Description
Top creators with username, platform, and view_contribution.
Name
peak_hour_utc
Type
integer
Description
UTC hour (0-23) when evidence videos were most commonly posted.
Name
status
Type
string
Description
One of new, rising, steady, or fading, compared to the previous Orbit with the same keywords (when available).

Trends for Orbits completed before April 22, 2026 were backfilled from the legacy analysis_data.themes object. Those records have name, why_it_works, video_count, and rank populated, but aggregate fields (total_views, platform_breakdown, top_creators, evidence_video_ids, tactics, confidence) are empty because that data was not captured upstream. New Orbits produce the full enriched shape.

Request

GET

/v1/orbit/:orbit_id/trends

curl -G https://api.virlo.ai/v1/orbit/f47ac10b-58cc-4372-a567-0e02b2c3d479/trends \
  -H "Authorization: Bearer {token}" \
  -d limit=50

Response

{
  "data": [
    {
      "id": "27585b73-fa9e-473e-8b4c-bcd03ecb2fde",
      "viral_insight_id": "0589e73f-114b-4e2c-bda9-787d843fb1f7",
      "reference_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "insight_type": "orbit",
      "batch_start": "2025-01-15T10:30:00.000Z",
      "batch_end": "2025-01-15T10:39:55.000Z",
      "rank": 1,
      "stable_key": "subway-crime-compilations",
      "name": "Subway crime compilations",
      "video_count": 48,
      "total_views": 18240000,
      "status": "new"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 5,
    "has_more": false
  }
}

GET/v1/orbit/:orbit_id/trends/latest

Get latest orbit trends

Returns the structured trends surfaced for this Orbit in the most recent analysis cycle, ranked by relevance. Each trend is a cluster of on-topic videos that share the same underlying subject, angle, format, or narrative driver — with evidence videos and aggregate statistics computed from them.

Trends are not limited to a fixed count: the analysis engine emits one entry per genuinely distinct trend in the video set. Each trend carries a stable_key reused across comparable batches (so you can pivot on it when you queue multiple Orbits with the same keywords over time).

Cost per request:Free

Path parameters

Name
orbit_id
Type
string
Required
*
Description
UUID of the Orbit job.

Request

GET

/v1/orbit/:orbit_id/trends/latest

curl https://api.virlo.ai/v1/orbit/f47ac10b-58cc-4372-a567-0e02b2c3d479/trends/latest \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "reference_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "insight_type": "orbit",
    "viral_insight_id": "0589e73f-114b-4e2c-bda9-787d843fb1f7",
    "batch_start": "2025-01-15T10:30:00.000Z",
    "batch_end": "2025-01-15T10:39:55.000Z",
    "total": 5,
    "trends": [
      {
        "id": "27585b73-fa9e-473e-8b4c-bcd03ecb2fde",
        "viral_insight_id": "0589e73f-114b-4e2c-bda9-787d843fb1f7",
        "insight_type": "orbit",
        "reference_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "batch_start": "2025-01-15T10:30:00.000Z",
        "batch_end": "2025-01-15T10:39:55.000Z",
        "rank": 1,
        "stable_key": "subway-crime-compilations",
        "name": "Subway crime compilations",
        "why_it_works": "Short, visceral clips tap into shared daily commuter frustration.",
        "tactics": ["shock-cut opener", "voiceover with sarcasm"],
        "confidence": 0.91,
        "evidence_video_ids": ["0c675286-d6e9-413f-9ff5-24138c6e2ff6"],
        "video_count": 48,
        "total_views": 18240000,
        "total_likes": 820000,
        "total_comments": 42100,
        "total_shares": 18700,
        "avg_virality_score": 4.92,
        "platform_breakdown": { "tiktok": 32, "youtube": 16 },
        "top_creators": [
          { "username": "nycpoliticalwatch", "platform": "tiktok", "view_contribution": 3200000 }
        ],
        "peak_hour_utc": 20,
        "status": "new",
        "first_seen_at": "2025-01-15T10:39:55.000Z",
        "prev_video_count": null,
        "prev_total_views": null
      }
    ]
  }
}

Async Workflow & State Machine

The Orbit keyword search follows an asynchronous queue-poll-retrieve pattern.

Status Flow

queued → processing → completed
                    → failed

Timing Expectations

Response times vary based on keyword count, meta_ads configuration, and current server load. Never hardcode timeouts — always poll until you receive a terminal status.

Configuration	Typical Duration
1-3 keywords, no meta_ads	2-5 minutes
5-10 keywords, no meta_ads	4-7 minutes
1-3 keywords, with meta_ads	3-6 minutes
5-10 keywords, with meta_ads	5-10 minutes
AI analysis generation	Automatic, adds ~1-2 minutes after search completes

These times are typical but not guaranteed. Under high traffic, jobs may take longer. Always continue polling until status reaches completed or failed. If no change after 15 minutes, the job may be experiencing delays but is still running.

Recommended Polling Strategy

Poll GET /v1/orbit/:orbit_id every 30 seconds. Polling is always free.

Step-by-Step Workflow

Queue a search: POST /v1/orbit with name, keywords, and optional filters — returns orbit_id and status: "queued"
Poll for status: GET /v1/orbit/:orbit_id — repeat every 30 seconds until status is "completed" or "failed"
Read the analysis: Use GET /v1/orbit/:orbit_id/analysis/latest for the full AI intelligence report and GET /v1/orbit/:orbit_id/trends/latest for detected trends
Retrieve detailed data (all free):
- GET /v1/orbit/:orbit_id/videos — paginated video results with filtering and sorting
- GET /v1/orbit/:orbit_id/slideshows — paginated slideshow (image carousel) results with filtering and sorting
- GET /v1/orbit/:orbit_id/ads — paginated Meta ads (only if enable_meta_ads was enabled)
- GET /v1/orbit/:orbit_id/creators/outliers — creators significantly outperforming their follower count

On Failure

If status is "failed", check the error message in the response. Common causes include invalid keywords or platform configuration. Retry with adjusted parameters.

Important: Search quality depends heavily on keyword specificity. Generic single words like "basketball" or "tech" yield scattered, unfocused results. Using specific keyword phrases like "NBA playoff highlights" or "iPhone 15 review" produces dramatically better, more targeted results.

Every Orbit search now automatically generates a comprehensive social intelligence report at no extra cost. Our proprietary analysis engine processes all collected videos and generates insights. This feature is perfect for:

Competitive intelligence: Understand what's working in your niche
Content strategy: Identify trending topics and successful formats
Creator insights: See which creators and content types dominate
Audience research: Learn what resonates with target demographics
Campaign planning: Use data-driven insights for marketing decisions

What's Included in the Analysis

Our social intelligence engine delivers a structured report with actionable insights across seven critical dimensions:

Top Trends (3-5 key findings)
- Breakthrough content with specific view counts
- Platform distribution and performance
- Emerging themes and breakout topics
- Verified vs organic creator performance
Thematic Category Sections (2-4 sections)
- Deep dives into relevant categories (e.g., Technology, Business, Entertainment)
- Top performers with engagement metrics
- Related topics and questions audiences are asking
- Comparative performance analysis
Platform Insights
- Distribution across YouTube, TikTok, Instagram
- Average views per platform
- Engagement rate differences
- Content format preferences
Creator & Influence Analysis
- Verified vs non-verified account performance
- Micro-creator vs established influencer reach
- Virality indicators and over-performers
- Follower-to-view ratio insights
Hashtag & Topic Clusters
- Most frequently used hashtags
- Emerging sub-topics
- Hashtag performance metrics
- Related topic connections
Sentiment & Narrative Breakdown
- Content sentiment distribution
- Dominant narratives and counter-narratives
- Performance by sentiment type
- Messaging effectiveness analysis
Viral Outliers & Notable Patterns
- Unexpected over-performers
- Timing and publishing patterns
- Format innovations
- Under-performers with quality content

Analysis Output Format

The analysis field returns markdown-formatted text. Example structure:

# AI Productivity Tools Social Media Landscape

November 9, 2025

Generated by Orbit by Virlo

---

## Top Trends

* @maverickgpt dominates with 1.54M views in just 8 hours
* ChatGPT tutorial content captured 58% of total videos
* "Vibe coding" emerges as breakout trend with CNN coverage
* AI tool discovery content spiked +300% week-over-week
* Prompt engineering tutorials achieved 89% higher bookmark rates

---

## Technology & Innovation

@maverickgpt is the top trending AI educator with 1.54M views...

Search interest in advanced ChatGPT techniques increased, and
prompt engineering is the top trending related topic...

Top questions about AI tools:

1. "Which AI tools are you using?" (@nate.b.jones - 131K views)
2. "How to make ChatGPT sound more human?" (@unlock.ai4 - 90K views)

---

## Platform Insights

TikTok dominated with 100% of content distribution across 12 videos,
generating 4.42M total views...

Regional performance breakdown:

- US creators: 42% of videos, 52% of total views
- International creators: 58% of videos, 48% of total views

---

Analysis based on 12 videos across TikTok
Searched keywords: AI productivity tools, ChatGPT tutorials
Time period: November 5-9, 2025
Execution time: 8 minutes, 32 seconds

Rendering the Analysis

To display the analysis in your application, parse it as markdown:

JavaScript/React example:

import ReactMarkdown from 'react-markdown'

function AnalysisDisplay({ analysis }) {
  return (
    <div className="prose">
      <ReactMarkdown>{analysis}</ReactMarkdown>
    </div>
  )
}

Python example:

import markdown

def display_analysis(analysis_text):
    html = markdown.markdown(analysis_text)
    return html

Best Practices

Use specific keyword phrases: Avoid generic single words like "basketball", "gaming", or "music" — they return scattered, unrelated content. Instead, use specific multi-word phrases like "NBA playoffs highlights", "Fortnite gameplay tips", or "Taylor Swift concert". Keyword sets (2-4 words) dramatically improve result quality and relevance.
Combine related keywords: Instead of ["jets"], use ["new york jets", "jets highlights", "jets game recap"] to capture comprehensive, targeted content
Set appropriate filters: min_views and time_period help focus on relevant content
Review the analysis field: Our intelligence reports complement raw video data with strategic insights
Save the analysis: Store reports for trend tracking over time
Compare analyses: Run multiple searches to compare different topics or time periods
Use paginated endpoints: For large result sets, use /v1/orbit/:orbit_id/videos instead of reading all videos from the main results endpoint
Discover outlier creators: Use /v1/orbit/:orbit_id/creators/outliers to find rising talent and potential partners

Pricing

Per-search cost is $0.50 (deducted from your prepaid balance). AI analysis and trend detection are included at no extra cost. See Billing & Pricing for how balance, 402 Payment Required, and headers (X-Credits-Used, X-Credits-Remaining, X-Cost, X-Balance-Remaining) work.

Professional Use Cases

The Orbit endpoint suite enables sophisticated social intelligence workflows across various industries:

Marketing & Brand Strategy

Competitive Intelligence

# Track competitor performance
curl -X POST https://api.virlo.ai/v1/orbit \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Competitor Analysis - Q4 2025",
    "keywords": ["competitor brand", "competitor product"],
    "platforms": ["youtube", "tiktok", "instagram"],
    "time_period": "this_month"
  }'

Campaign Performance Monitoring

import requests

# Monitor campaign hashtags
response = requests.post(
    'https://api.virlo.ai/v1/orbit',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'name': 'Campaign Impact Analysis',
        'keywords': ['#YourCampaign', 'brand mention', 'product launch'],
        'time_period': 'this_week',
        'min_views': 10000
    }
)

Content Strategy & Creator Insights

Trend Discovery

Identify emerging topics before they peak
Discover successful content formats
Track viral content patterns
Analyze creator strategies

Content Gap Analysis

Find underserved topics with high potential
Identify content opportunities competitors missed
Discover audience questions needing answers

Product Development & Research

Customer Sentiment Analysis

// Monitor product mentions
const response = await fetch('https://api.virlo.ai/v1/orbit', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Product Sentiment - Weekly Check',
    keywords: ['your product', 'product reviews', 'unboxing'],
    platforms: ['youtube', 'tiktok'],
    time_period: 'this_week',
  }),
})

Market Research

Understand customer pain points through social conversations
Track feature requests and product feedback
Monitor competitor product launches
Identify market trends and shifts

Agency & Consulting

Client Reporting

Generate comprehensive social listening reports
Track multiple client campaigns simultaneously
Provide data-driven strategic recommendations
Monitor industry trends for client portfolios

Performance Benchmarking

Compare client performance vs competitors
Track industry averages and top performers
Identify best-in-class examples
Measure campaign effectiveness

Integration Patterns

Scheduled Analysis (Cron Job)

Monitor topics continuously with automated polling:

import requests
import time
from datetime import date

def queue_weekly_analysis():
    """Queue a new analysis every Monday"""
    response = requests.post(
        'https://api.virlo.ai/v1/orbit',
        headers={'Authorization': f'Bearer {API_KEY}'},
        json={
            'name': f'Weekly Industry Trends - {date.today()}',
            'keywords': ['industry trend', 'market news', 'competitor'],
            'time_period': 'this_week'
        }
    )
    return response.json()['data']['orbit_id']

def poll_until_complete(orbit_id):
    """Poll for results with exponential backoff"""
    wait_time = 30  # Start with 30 seconds
    max_wait = 300  # Max 5 minutes between polls

    while True:
        response = requests.get(
            f'https://api.virlo.ai/v1/orbit/{orbit_id}',
            headers={'Authorization': f'Bearer {API_KEY}'}
        )
        result = response.json()['data']

        if result['status'] == 'completed':
            return result
        elif result['status'] == 'failed':
            raise Exception(f"Analysis failed: {result.get('error')}")

        time.sleep(wait_time)
        wait_time = min(wait_time * 1.5, max_wait)  # Exponential backoff

def fetch_all_videos(orbit_id):
    """Fetch all videos using pagination"""
    all_videos = []
    page = 1

    while True:
        response = requests.get(
            f'https://api.virlo.ai/v1/orbit/{orbit_id}/videos',
            headers={'Authorization': f'Bearer {API_KEY}'},
            params={'limit': 100, 'page': page, 'order_by': 'views', 'sort': 'desc'}
        )
        data = response.json()['data']
        all_videos.extend(data['videos'])

        if len(all_videos) >= data['total']:
            break
        page += 1

    return all_videos

Webhook Integration (Coming Soon)

Receive notifications when analysis jobs complete:

// Future webhook payload example
{
  "event": "orbit.analysis.completed",
  "orbit_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "AI Tools Trend Analysis",
  "status": "completed",
  "completed_at": "2025-11-09T06:45:23Z"
}

Dashboard Integration

Display analysis in your dashboard:

// Next.js example
import ReactMarkdown from 'react-markdown'
import { useEffect, useState } from 'react'

export function OrbitAnalysisDashboard({ orbitId }: { orbitId: string }) {
  const [data, setData] = useState(null)
  const [loading, setLoading] = useState(true)

  useEffect(() => {
    async function fetchAnalysis() {
      const response = await fetch(
        `https://api.virlo.ai/v1/orbit/${orbitId}`,
        {
          headers: { Authorization: `Bearer ${process.env.VIRLO_API_KEY}` }
        }
      )
      const result = await response.json()
      setData(result.data)
      setLoading(false)
    }

    const interval = setInterval(fetchAnalysis, 30000) // Poll every 30s
    fetchAnalysis()
    return () => clearInterval(interval)
  }, [orbitId])

  if (loading) return <LoadingSpinner />
  if (data?.status !== 'completed') return <ProcessingIndicator />

  return (
    <div>
      <h1>{data.name}</h1>
      <div className="prose prose-lg max-w-none">
        <ReactMarkdown>{data.analysis}</ReactMarkdown>
      </div>
      <VideoGrid videos={data.results.videos} />
    </div>
  )
}

Error responses

The Orbit endpoints may return the following error codes:

Name
400 Bad Request
Description
Invalid parameters provided. Common causes include: - Missing required 'name' field - Keywords array must contain 1-10 elements - Invalid platform values (must be 'youtube', 'tiktok', or 'instagram') - Invalid time_period value - Invalid order_by field - Orbit search not found
Name
401 Unauthorized
Description
Missing or invalid API key. Ensure you're including your API key in the Authorization header.
Name
429 Too Many Requests
Description
Rate limit exceeded. Your plan has specific rate limits per endpoint. Wait before making additional requests.