Workflow Recipes
Step-by-step guides for common multi-endpoint workflows. Each recipe shows the full sequence of API calls, expected timing, and total dollar cost (deducted from your prepaid balance).
These recipes show which API calls to make and in what order. Retrieval endpoints (videos, ads, outliers) are always free — you only pay for the initial search or analysis. To understand what the numbers mean (virality scoring, intelligence fields, platform benchmarks), see the Agent Playbook. If you're wiring up Cursor or Claude, give your assistant /agent-playbook.txt instead of asking it to scrape this HTML page.
Full Niche Analysis
The most comprehensive research workflow. Search for any topic, get an AI intelligence report, explore videos, ads, and find rising creators.
Total cost: $0.50 (+ $0.50 per optional creator deep-dive; + $1.00 with Data Intelligence). All retrieval is free.
Expected time: ~15–20 minutes for a typical Orbit run end to end (including the AI analysis); simple single-platform runs can finish in a few minutes, broad runs with meta ads can take up to 45. Don't assume a job is stuck — poll until finalized: true.
Step 1: Queue an Orbit search ($0.50)
Queue Search
curl -X POST https://api.virlo.ai/v1/orbit \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"name": "Jeep Wrangler Mods Research",
"keywords": ["jeep wrangler mods", "jeep wrangler accessories", "jeep upgrades"],
"time_period": "this_month",
"platforms": ["youtube", "tiktok", "instagram"],
"enable_meta_ads": true
}'
Step 2: Poll until finalized (free)
Poll GET /v1/orbit/:orbit_id every 60 seconds. Do not set a hard timeout — response times vary with keyword count, meta_ads, and server load. Wait for finalized: true, not just status: "completed" — the main scrape can finish while the AI analysis is still generating (see the Async Data Model). And treat partial_failure as usable: it means one platform or keyword failed but the rest of the data was collected.
Poll Status
# Step 2: Poll until everything (scrape + AI analysis) is done
while True:
result = requests.get(
f'https://api.virlo.ai/v1/orbit/{orbit_id}',
headers={'Authorization': 'Bearer YOUR_API_KEY'}
).json()['data']
if result.get('finalized'):
break
if result['status'] == 'failed':
raise Exception('Search failed')
# status 'completed' or 'partial_failure' with finalized=False just
# means secondary AI jobs are still running — keep polling.
time.sleep(60)
# Read the AI intelligence report (now guaranteed populated)
print(result['analysis'])
Step 3: Retrieve videos, ads, and outliers (free)
Retrieve Results
# Top videos sorted by views
videos = requests.get(
f'https://api.virlo.ai/v1/orbit/{orbit_id}/videos',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
params={'limit': 50, 'order_by': 'views', 'sort': 'desc'}
).json()['data']
# Meta ad campaigns
ads = requests.get(
f'https://api.virlo.ai/v1/orbit/{orbit_id}/ads',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
params={'limit': 50}
).json()['data']
# Rising creators outperforming their follower count.
# Sort by weighted_score (ln(outlier_ratio) x ln(followers)) — it balances
# outperformance against audience size and is what Virlo's own UI uses.
outliers = requests.get(
f'https://api.virlo.ai/v1/orbit/{orbit_id}/creators/outliers',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
params={'limit': 20, 'order_by': 'weighted_score', 'sort': 'desc'}
).json()['data']
Step 4 (Optional): Deep-dive into standout creators ($0.50 each)
For creators from the outliers list, run a Satellite lookup for full profile analysis.
Creator Deep Dive
Analyze a specific creator's profile, engagement metrics, posting patterns, and identify their content outliers.
Total cost: $1.00 ($0.50 for creator lookup + $0.50 for video outlier).
Expected time: 30-90 seconds for both jobs.
Step 1: Start creator lookup ($0.50)
Creator Lookup
curl "https://api.virlo.ai/v1/satellite/creator/tiktok/hatimsshorts?include=videos,outliers&max_videos=20" \
-H "Authorization: Bearer {token}"
Step 2: Analyze the top video ($0.50)
Video Outlier
# Get the top-performing video URL from the creator's videos
top_video = max(creator['videos'], key=lambda v: v['views'])
# Start video outlier analysis
response = requests.post(
'https://api.virlo.ai/v1/satellite/video-outlier',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
json={'url': top_video['url'], 'platform': 'tiktok'}
)
job_id = response.json()['data']['job_id']
# Poll until complete
while True:
result = requests.get(
f'https://api.virlo.ai/v1/satellite/video-outlier/status/{job_id}',
headers={'Authorization': 'Bearer YOUR_API_KEY'}
).json()['data']
if result['status'] == 'completed':
break
time.sleep(10)
analysis = result['result']['analysis']
print(f"Outlier score: {analysis['outlier_score']}")
print(f"Percentile: {analysis['percentile']}")
print(f"Label: {analysis['performance_label']}")
Trend Monitoring Setup
Discover trending topics, research them in depth, and set up automated monitoring.
Total cost: $1.25 initial ($0.25 trends digest + $0.50 Orbit + $0.50 Comet), then automated runs on your chosen cadence.
Step 1: Check today's trends ($0.25)
Get Trends
import requests
trends = requests.get(
'https://api.virlo.ai/v1/trends/digest',
headers={'Authorization': 'Bearer YOUR_API_KEY'}
).json()['data']
for group in trends:
print(f"\n{group['title']}")
for item in group['trends']:
print(f" #{item['ranking']}: {item['trend']['name']}")
Step 2: Research an interesting trend with Orbit ($0.50)
Use keywords from the trend to queue a comprehensive search.
Step 3: Convert to Comet for ongoing monitoring ($0.50)
Create Comet
response = requests.post(
'https://api.virlo.ai/v1/comet',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
json={
'name': 'Trend Monitoring - Devil Wears Prada 2',
'keywords': ['Devil Wears Prada 2', 'Devil Wears Prada sequel', 'Prada 2 merch'],
'platforms': ['youtube', 'tiktok', 'instagram'],
'cadence': 'weekly',
'min_views': 0,
'time_range': 'this_month',
'is_active': True,
'meta_ads_enabled': True
}
)
comet = response.json()['data']
print(f"Next run: {comet.get('next_run_at', 'scheduled')}")
Hashtag Research
Explore hashtag performance across platforms and drill into specific hashtags.
Total cost: $0.05–$0.25 depending on depth (each hashtag list or performance call is $0.05; platform-specific calls add $0.05 each).
Hashtag Research
import requests
from datetime import date, timedelta
headers = {'Authorization': 'Bearer YOUR_API_KEY'}
end = date.today().isoformat()
start = (date.today() - timedelta(days=30)).isoformat()
# Top hashtags by views ($0.05)
hashtags = requests.get(
'https://api.virlo.ai/v1/hashtags',
headers=headers,
params={'start_date': start, 'end_date': end, 'limit': 20, 'order_by': 'views', 'sort': 'desc'}
).json()['data']
# Drill into a specific hashtag ($0.05)
perf = requests.get(
f'https://api.virlo.ai/v1/hashtags/fyp/performance',
headers=headers,
params={'start_date': start, 'end_date': end}
).json()['data']
print(f"#fyp: {perf['video_count']} videos, {perf['total_views']:,} views, avg {perf['avg_views']:,.0f} views/video")
# Platform-specific hashtags ($0.05 each)
tiktok = requests.get(
'https://api.virlo.ai/v1/tiktok/hashtags',
headers=headers,
params={'start_date': start, 'end_date': end, 'limit': 10, 'order_by': 'views', 'sort': 'desc'}
).json()['data']