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.

All Orbit V1 endpoints use the base URL https://api.virlo.ai/v1/orbit. All parameter names and response fields use snake_case. All responses are wrapped in a { "data": { ... } } envelope.

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
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. Example: 30000
Name
time_period
Type
string
Description
Time period filter for video publish date. Options: today, this_week, this_month, this_year.
Name
run_analysis
Type
boolean
Description
Enable Virlo's proprietary social intelligence analysis. When enabled, our analysis engine processes all collected videos and generates a comprehensive social listening brief with strategic insights. 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.

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",
    "run_analysis": true,
    "enable_meta_ads": false,
    "exclude_keywords": ["spam", "irrelevant"],
    "exclude_keywords_strict": false
  }'

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, credit usage, and optionally a Virlo social intelligence report.

Cost per request:(polling is always free)

Important: If you enabled run_analysis: true when queuing the job, the analysis field will contain a comprehensive social intelligence report analyzing all discovered videos, trends, and audience behavior patterns.

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
Virlo social intelligence report as a markdown-formatted string. Only present when run_analysis: true was set during job creation and the search is completed. Contains comprehensive insights including top trends, platform performance, creator analysis, hashtag clusters, sentiment breakdown, and viral outliers with specific metrics and percentages.
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
results
Type
object
Description
Contains total_videos, youtube_count, tiktok_count, instagram_count, trends, videos, 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"],
    "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.

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"
      }
    ]
  }
}

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 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. 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,
        "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"]
          }
        ]
      }
    ]
  }
}

Usage workflow

The Orbit keyword search follows an asynchronous pattern:

Queue a search: POST to /v1/orbit with a name, keywords, and optional filters
Get orbit_id: Save the returned orbit_id from the response
Poll for results: GET /v1/orbit/:orbit_id to check status
Retrieve data: Once status: "completed", access the full results with videos, trends, insights, and optionally a Virlo social intelligence report
Browse results: Use the paginated endpoints to drill into specific data:
- GET /v1/orbit/:orbit_id/videos — paginated video results with filtering
- GET /v1/orbit/:orbit_id/ads — paginated Meta ads (if enable_meta_ads was enabled)
- GET /v1/orbit/:orbit_id/creators/outliers — creators outperforming their follower count

The analysis job typically takes 5-10 minutes per keyword. If run_analysis: true was set, expect an additional 1-2 minutes for intelligence report generation. Poll every 30-60 seconds for optimal performance.

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.

When you set run_analysis: true during job creation, our proprietary analysis engine automatically processes all collected videos and generates a comprehensive social intelligence report. 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

Credit Costs

Credit costs are dynamically set based on computational requirements. Visit your Dashboard Pricing for current costs.

Without analysis (run_analysis: false or omitted): Base credits per search
With intelligence analysis (run_analysis: true): Base credits + analysis processing (varies by result size)

The additional cost for intelligence analysis is automatically calculated based on the number of videos analyzed and the depth of insights generated.

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",
    "run_analysis": true
  }'

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,
        'run_analysis': True
    }
)

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',
    run_analysis: true,
  }),
})

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',
            'run_analysis': True
        }
    )
    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",
  "credits_used": 12.5,
  "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.