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 receive comprehensive insights about the short-form social media landscape.

Queue keyword search

curl -X POST https://api.virlo.ai/orbit/keyword-search \
  -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"],
    "minViews": 10000,
    "timePeriod": "this_week",
    "runAnalysis": true
  }'

{
  "results": 1,
  "data": {
    "orbitId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "queued",
    "message": "Social listening analysis job queued successfully."
  }
}

Get search results

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

{
  "results": 1,
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "processing",
    "startedAt": "2025-11-11T05:30:00.000Z",
    "name": "NYC Mayoral Race Social Listening",
    "keywords": ["NYC mayor election 2025", "Eric Adams", "Scott Stringer"],
    "results": null
  }
}

List searches

curl -G https://api.virlo.ai/orbit/keyword-search \
  -H "Authorization: Bearer {token}" \
  -d limit=10 \
  -d offset=0

{
  "results": 2,
  "data": {
    "total": 47,
    "limit": 10,
    "offset": 0,
    "orbits": [
      {
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "name": "NYC Mayoral Race Social Listening",
        "keywords": ["NYC mayor election 2025", "Eric Adams", "Scott Stringer"],
        "platforms": ["youtube", "tiktok"],
        "status": "completed",
        "totalVideos": 21,
        "createdAt": "2025-11-11T05:30:00.000Z",
        "executionTimeMs": 495000
      },
      {
        "id": "a12bc34d-56ef-7890-g123-h456i789j012",
        "name": "Gaming Industry Sentiment Analysis",
        "keywords": ["new game releases", "gaming reviews", "esports"],
        "platforms": ["youtube", "tiktok"],
        "status": "processing",
        "totalVideos": null,
        "createdAt": "2025-11-11T02:15:00.000Z",
        "executionTimeMs": null
      }
    ]
  },
  "pagination": {
    "total": 47,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

Usage workflow

The Orbit keyword search follows an asynchronous pattern:

1. Queue a search: POST to /orbit/keyword-search with a name, keywords, and optional filters
2. Get orbitId: Save the returned orbitId from the response
3. Poll for results: GET /orbit/keyword-search/:orbitId to check status
4. Retrieve data: Once status: "completed", access the full results with videos, trends, insights, and optionally a Virlo social intelligence report

The analysis job typically takes 5-15 minutes depending on the number of keywords and platforms selected. If runAnalysis: 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.

Virlo Social Intelligence Analysis

When you set runAnalysis: 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:

1. 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

2. 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

3. Platform Insights

   • Distribution across YouTube, TikTok, Instagram
   • Average views per platform
   • Engagement rate differences
   • Content format preferences

4. 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

5. Hashtag & Topic Clusters

   • Most frequently used hashtags
   • Emerging sub-topics
   • Hashtag performance metrics
   • Related topic connections

6. Sentiment & Narrative Breakdown

   • Content sentiment distribution
   • Dominant narratives and counter-narratives
   • Performance by sentiment type
   • Messaging effectiveness analysis

7. 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: minViews and timePeriod 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

Credit Costs

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/orbit/keyword-search \
  -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"],
    "timePeriod": "this_month",
    "runAnalysis": true
  }'

Campaign Performance Monitoring

import requests

# Monitor campaign hashtags
response = requests.post(
    'https://api.virlo.ai/orbit/keyword-search',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'name': 'Campaign Impact Analysis',
        'keywords': ['#YourCampaign', 'brand mention', 'product launch'],
        'timePeriod': 'this_week',
        'minViews': 10000,
        'runAnalysis': 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/orbit/keyword-search', {
  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'],
    timePeriod: 'this_week',
    runAnalysis: 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

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

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/orbit/keyword-search/{orbit_id}',
            headers={'Authorization': f'Bearer {API_KEY}'}
        )
        data = response.json()

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

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

Webhook Integration (Coming Soon)

Receive notifications when analysis jobs complete:

// Future webhook payload example
{
  "event": "orbit.analysis.completed",
  "orbitId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "AI Tools Trend Analysis",
  "status": "completed",
  "creditsUsed": 5000,
  "completedAt": "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/orbit/keyword-search/${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: