# Virlo API

> Social media intelligence API for TikTok, YouTube Shorts, and Instagram Reels. Track viral content, hashtags, trends, and creators with real-time analytics across 21K+ creators daily.

Virlo provides programmatic access to social media analytics through a REST API. The core research surface is Content Research Agents (POST /v1/agents) for one-shot and recurring niche research. Also: Satellite (creator/video/sound intel), Tracking (long-term monitoring), Sounds, Trends, Hashtags, and video digests across TikTok, YouTube Shorts, and Instagram Reels. Orbit (/v1/orbit) and Comet (/v1/comet) are DEPRECATED shims for Agents — removed August 3, 2026.

Base URL: https://api.virlo.ai/v1
Authentication: Bearer token in Authorization header (format: virlo_tkn_<your_key>)
Get your API key: https://dev.virlo.ai/dashboard
All parameter names and response fields use snake_case.
All responses are wrapped in a { "data": { ... } } envelope.

## Billing

Pay-as-you-go prepaid balance. Add funds in Billing (minimum shown there; A/B tested via api-min-topup-amount), use the API, auto top-up keeps you running. No subscriptions. Balance never expires.
Response headers: X-Cost and X-Credits-Used appear on every response ("0.00"/"0" for free reads); X-Credits-Remaining and X-Balance-Remaining appear only on charged responses (cost > 0).
- $0.05: Hashtag endpoints (list, performance, platform-specific), Sound detail, Sound usage history
- $0.10: Sound search
- $0.25: Video digest endpoints, Trends endpoints, tracking creator/video (charged at the POST — covers the initial cycle; auto-refunded if that first cycle can't resolve the creator/video; each subsequent recurring cycle is another $0.25), Trending sounds, Breakout sounds, Sound videos, Creator sounds
- $0.50: POST /v1/agents (one-shot, is_recurring=false) — recurring agents (is_recurring=true) are free to create and bill $0.50 per scheduled run; Orbit queue (DEPRECATED), Comet creation (DEPRECATED), Satellite creator lookup, Video Outlier analysis
- +$1.00: Data Intelligence add-on (POST /v1/agents; also legacy Orbit/Comet) — 43 AI fields per video AND a parallel schema on every slideshow when data_intelligence_enabled=true. Both surface a per-item `intelligence_status` (ready/pending/disabled/failed/skipped) so agents can tell "still waiting" from "never coming". When intent is provided with intelligence, each video gets an intent_match result and the response includes intent_summary with matched_urls
- Free: Agent data retrieval (videos, slideshows, ads, outliers, analysis, trends, sounds, hashtags, benchmarks, affinity, similar), Tracking reads, status polling, account balance, emerging trends. Legacy Orbit/Comet reads remain free during the migration window.
When balance reaches zero, API returns 402 Payment Required. Auto top-up is enabled by default.
Add funds at https://dev.virlo.ai/dashboard/billing

## Guides

- [Quickstart](https://dev.virlo.ai/docs/quickstart): Get your API key and make your first request
- [Authentication](https://dev.virlo.ai/docs/authentication): API key format and Bearer token usage
- [Pagination](https://dev.virlo.ai/docs/pagination): The API's four pagination shapes (nested+offset, pagination envelope, count-only, unpaginated), how to tell them apart, and the limit/default exceptions
- [Billing & Pricing](https://dev.virlo.ai/docs/credits): Pay-as-you-go pricing, auto top-up, per-endpoint costs
- [Rate Limits](https://dev.virlo.ai/docs/rate-limits): Default rate limits per endpoint, response headers, best practices for high-volume pipelines
- [AI Agent Integration](https://dev.virlo.ai/docs/ai-agents): For developers — how to connect Cursor, Claude, OpenClaw, or MCP to Virlo
- [Agent Playbook](https://dev.virlo.ai/agent-playbook.txt): If you are an AI assistant, fetch this next — it explains how to route your user's intent to the right workflow and how to interpret results (virality scoring, intelligence fields, platform benchmarks).
- [Recipes](https://dev.virlo.ai/docs/recipes): Multi-endpoint workflow guides (Full Niche Analysis, Creator Deep Dive)
- [Async Data Model](https://dev.virlo.ai/docs/async-data): finalized, pending_jobs[], intelligence_status — how to know when a resource is truly done

## Async Endpoints (queue-poll pattern)

- [Content Research Agents](https://dev.virlo.ai/docs/agents): POST /v1/agents to create a one-shot (is_recurring=false, replaces Orbit) or recurring (is_recurring=true, replaces Comet) research agent ($0.50 to create; recurring bills per scheduled run; reads free). Collection scope is SYSTEM-MANAGED — you do NOT set min_views/time_range at creation; the system collects broadly and you FILTER AT READ TIME on GET /v1/agents/:id/videos (min_views, start_date, end_date, platforms, order_by, region). Set english_only=false at creation to collect content in ALL languages (write keywords/intent in the target language). Filter by upload country at read time with region=<ISO-3166-1 alpha-2> on /videos and /slideshows — each carries upload_region/region (BETA: deterministic where the platform provides it, AI-inferred otherwise; slideshows have the highest coverage). Retrieve videos/slideshows/ads/runs, analysis (GET /v1/agents/:id/analysis/latest + history), trends (GET /v1/agents/:id/trends/latest + history, stable_key time-series), sounds (sort=rising/growth_7d), hashtags (volume/growth/avg_views + top creators), creators/outliers (order_by=rising + follower_tier/category filters), benchmarks (genre norms by follower tier), affinity (genre adjacency), and creators/:creator_id/similar — full superset of every Orbit + Comet read at the same sub-paths (IDs are interchangeable). Self-optimizing autonomy: GET /v1/agents/:id/activity + /proposals, apply/dismiss/revert proposals, PUT /v1/agents/:id/autonomy (suggest|autopilot). Webhook: content_research_agent.run.completed. This is the unified replacement for Orbit + Comet, which are DEPRECATED and removed on August 3, 2026.
- [Suggest Keywords](https://dev.virlo.ai/docs/agents#suggest-keywords): POST /v1/agents/suggest-keywords — FREE, synchronous, creates nothing. Turns an intent into a quality-graded keyword set (keywords, exclude_keywords, reasoning, quality.score 0-100 + passes + issues[] + stats) you can pass straight to POST /v1/agents. ALWAYS call this before paying to create an agent; iterate until quality.passes is true. Params: intent (required, ≤500 chars), topic_hint, platforms, existing_keywords, mode (create|refresh|opportunity), desired_count (engine clamps to the 7-12 sweet spot), use_web_grounding.
- [Orbit - Social Listening](https://dev.virlo.ai/docs/orbit): (DEPRECATED — migrate to /v1/agents, removed August 3, 2026) POST /v1/orbit to queue keyword search, GET /v1/orbit/:orbit_id to poll, then retrieve videos/slideshows/ads/outliers/analysis/trends ($0.50 to queue, free to retrieve). Typical completion 10-25 minutes; poll every 60s and rely on the finalized field, not wall-clock expectations. Status partial_failure means one platform/keyword failed but the rest of the data is present — treat it like completed. Optional: intent + data_intelligence_enabled=true for intent-based filtering using 43 AI fields per video (+$1.00); english_only=false to collect all languages; region=<ISO-3166-1 alpha-2> to filter videos/slideshows by upload country at read time (BETA)
- [Comet - Custom Niche](https://dev.virlo.ai/docs/comet): (DEPRECATED — migrate to /v1/agents with is_recurring=true, removed August 3, 2026) POST /v1/comet to create automated monitoring, runs on cadence (daily/weekly/monthly) ($0.50 to create, free to retrieve videos/slideshows/ads/outliers/analysis/trends). For TikTok-genre discovery, free reads also include sounds (sort=rising/growth_7d), hashtags (volume/growth/avg_views + top creators), creators/outliers with order_by=rising + follower_tier/category filters, benchmarks (genre norms by follower tier), affinity (genre adjacency), and creators/:creator_id/similar. Hashtag-style keyword tokens are normalized (#progressivehouse == progressive house). Optional: intent + data_intelligence_enabled=true for intent-based filtering using 43 AI fields per video (+$1.00); english_only=false to monitor all languages; region=<ISO-3166-1 alpha-2> to filter videos/slideshows by upload country at read time (BETA)
- [Satellite - Creator Lookup](https://dev.virlo.ai/docs/satellite): GET /v1/satellite/creator/:platform/:username to start, poll status/:job_id ($0.50 base, completes in 20-60s; +$0.50 with trend_analysis=true to also run AI trend detection over the creator's body of work, 60-120s). Profile includes AI-inferred category. Videos include is_duet/is_stitch flags (TikTok). Persisted as a durable run — re-read via /v1/satellite/runs/:run_id is free.
- [Satellite - Batch Creator Lookup](https://dev.virlo.ai/docs/satellite): POST /v1/satellite/creators/batch to look up multiple creators at once (up to 25). Per-handle pricing. Poll GET /v1/satellite/creators/batch/:batch_id for aggregate status.
- [Video Outlier Analysis](https://dev.virlo.ai/docs/satellite/video-outlier): POST /v1/satellite/video-outlier to start, poll status/:job_id ($0.50, completes in 20-60s)
- [Satellite - Sound Lookups](https://dev.virlo.ai/docs/satellite/sounds): GET /v1/satellite/sounds/:platform/:music_id (platform tiktok|instagram — YouTube not supported) — every video using a sound + aggregate stats (views, engagement, velocity, top creators/hashtags). $0.50 base; +$0.50 with trend_analysis=true for LLM trend detection over ~300 videos (time_windows, resurged, momentum per trend). Poll GET /v1/satellite/sounds/status/:job_id (free). Sound lookups are slower than creator lookups: ~8 min average, poll every 30s.
- [Satellite - Durable Runs](https://dev.virlo.ai/docs/satellite#durable-runs): every paid satellite run persists a run_id. GET /v1/satellite/runs/:run_id re-reads the full result FREE, forever (+ GET /v1/satellite/runs history list with type/platform filters, + /runs/:run_id/videos paginated). Save run_ids and re-read instead of re-buying — only new lookups cost credits.

## Tracking Endpoints (creator & video monitoring)

- [Tracking - Creator & Video Monitoring](https://dev.virlo.ai/docs/tracking): Track creators and videos over time with configurable cadences
  - POST /v1/tracking/creators — start tracking a creator ($0.25 charged at the POST; auto-refunded if the first cycle can't resolve; each subsequent cycle is another $0.25). AI reports auto-generated each cycle.
  - GET /v1/tracking/creators — list tracked creators (free)
  - GET /v1/tracking/creators/:id — get creator details (free)
  - GET /v1/tracking/creators/:id/report — get latest AI report (free, auto-generated)
  - GET /v1/tracking/creators/:id/snapshots — get metric snapshots with optional start_date, end_date, limit (free). Includes total_views (all platforms), collected_post_count, and delta_* fields.
  - GET /v1/tracking/creators/:id/posts — list creator's collected posts with pagination, date filtering, and TikTok duet/stitch flags (free)
  - GET /v1/tracking/creators/:id/posts/:post_id — get single post detail with full metrics (free)
  - POST /v1/tracking/creators/:id/posts/collect — trigger on-demand deep video collection. Depth tiers: standard (50 videos, $0.50), deep (200 videos, $1.00), full (500 videos, $2.00)
  - GET /v1/tracking/creators/:id/posts/collect/:collection_id — poll collection job status (free)
  - GET /v1/tracking/creators/:id/posting-cadence — get posting frequency analytics derived from collected posts (free)
  - PATCH /v1/tracking/creators/:id — update status or scrape_cadence (free)
  - DELETE /v1/tracking/creators/:id — stop tracking (free)
  - POST /v1/tracking/videos — start tracking a video ($0.25 charged at the POST; auto-refunded if the first cycle can't resolve; each subsequent cycle is another $0.25). AI reports auto-generated each cycle.
  - GET /v1/tracking/videos — list tracked videos (free)
  - GET /v1/tracking/videos/:id — get video details (free)
  - GET /v1/tracking/videos/:id/report — get latest AI report (free, auto-generated)
  - GET /v1/tracking/videos/:id/snapshots — get metric snapshots (free)
  - PATCH /v1/tracking/videos/:id — update status or scrape_cadence (free)
  - DELETE /v1/tracking/videos/:id — stop tracking (free)

## Audience Endpoints

- [Audience demographics & geography](https://dev.virlo.ai/docs/tracking): Who actually watches a tracked creator — age/gender split and country breakdown. Requires the creator to be tracked first.
  - GET /v1/tracking/creators/:id/audience-demographics — age/gender breakdown for a tracked creator (free once generated)
  - GET /v1/tracking/creators/:id/audience-geography — country/region breakdown for a tracked creator (free once generated)
  - POST /v1/tracking/creators/:id/audience-refresh — queue a fresh audience snapshot (async, billed). Returns a job_id.
  - GET /v1/tracking/creators/:id/audience-refresh/:jobId — poll a tracking-scoped audience refresh job (free)
  - GET /v1/audience/snapshot/:job_id — generic audience-snapshot poll that works for ANY audience job regardless of origin (satellite-path or tracking-path). Prefer this when you only have a job_id.
  - Async: subscribe to the audience.snapshot.completed webhook instead of polling. Demographics/geography fields are null until the snapshot finishes — null means "not yet", not "no data".

## Sound Endpoints

- GET /v1/sounds/trending — sounds currently trending in the Virlo dataset. Default sort `videos_7d` (real recent velocity); also `videos_30d`, `usage_count` (legacy all-time), `video_count` (legacy) ($0.25). Filter by platform, commerce_only.
- GET /v1/sounds/breakout — sounds with high recent-burst ratio (rapidly rising from a small baseline). Distinct from trending — trending = high absolute momentum, breakout = high relative momentum. Returns videos_7d/30d/90d, burst_ratio, breakout_score ($0.25). Filter by platform, commerce_only, min_recent, min_baseline.
- GET /v1/sounds/search?q=... — fuzzy search sounds by title ($0.10). ~68K sounds, growing daily.
- GET /v1/sounds/:sound_id — full sound details + aggregate stats + track_resolution object ($0.05; resolve=true adds $0.10 on a fresh sound→recording match via ISRC/Spotify, cached resolutions free)
- GET /v1/sounds/:sound_id/videos — videos using a specific sound ($0.25)
- GET /v1/sounds/:sound_id/usage-history — daily usage_count time-series with delta fields ($0.05)
- GET /v1/sounds/by-creator/:platform/:handle — all sounds owned by a creator + UGC metrics ($0.25)
- GET /v1/agents/:id/sounds — top sounds in an agent run; sort=rising/growth_7d for momentum (free)
- GET /v1/agents/:id/hashtags — per-hashtag analytics, growth + top creators (free)
- GET /v1/orbit/:orbit_id/sounds · GET /v1/comet/:comet_id/sounds · GET /v1/comet/:comet_id/hashtags — legacy aliases (DEPRECATED, free)
- All video responses now include an optional "sound" object with audio metadata (additive, non-breaking).
- Platform field availability: TikTok (richest: title, duration, cover_url, usage_count, is_commerce_music, is_original, owner info). YouTube (moderate: title, cover_url, owner_nickname, owner_id). Instagram (sparsest: title, owner_nickname only). Unavailable fields return null.

## Sync Endpoints

- [Hashtags](https://dev.virlo.ai/docs/hashtags): GET /v1/hashtags with date range, GET /v1/hashtags/:hashtag/performance ($0.05)
- [Trends](https://dev.virlo.ai/docs/trends): GET /v1/trends, GET /v1/trends/digest ($0.25) - regional via ?region= (global default, us, gb, au; more over time); GET /v1/trends/regions lists codes (free). Each trend carries a live momentum object (status new/rising/steady/fading, 0-1 score, views_per_hour) refreshed ~every 2h. GET /v1/trends/emerging (free, rate-limited, ?region=) returns a flat momentum-ranked list of early-stage (new/rising) trends — "what's emerging in the UK right now"
- [Videos](https://dev.virlo.ai/docs/videos): GET /v1/videos/digest - top videos from last 48 hours ($0.25)
- Account: GET /v1/account/balance - check credit balance and pricing (free)

## Platform-Specific

- [YouTube Hashtags](https://dev.virlo.ai/docs/youtube-hashtags): GET /v1/youtube/hashtags ($0.05)
- [YouTube Videos](https://dev.virlo.ai/docs/youtube-videos): GET /v1/youtube/videos/digest ($0.25)
- [TikTok Hashtags](https://dev.virlo.ai/docs/tiktok-hashtags): GET /v1/tiktok/hashtags ($0.05)
- [TikTok Videos](https://dev.virlo.ai/docs/tiktok-videos): GET /v1/tiktok/videos/digest ($0.25)
- [Instagram Hashtags](https://dev.virlo.ai/docs/instagram-hashtags): GET /v1/instagram/hashtags ($0.05)
- [Instagram Videos](https://dev.virlo.ai/docs/instagram-videos): GET /v1/instagram/videos/digest ($0.25)

## Full Documentation

- [Complete API Reference (llms-full.txt)](https://dev.virlo.ai/llms-full.txt): Full endpoint specs, response schemas, async workflow state machines, and code examples - optimized for LLM consumption
- [Agent Playbook (agent-playbook.txt)](https://dev.virlo.ai/agent-playbook.txt): Intent routing, result interpretation, virality math, and intelligence field semantics - the "how to think" companion to the reference
- [OpenAPI Specification](https://api.virlo.ai/openapi.json): Machine-readable API spec (JSON)
- [Interactive Playground](https://dev.virlo.ai/docs/playground): Test endpoints with mock data

## Optional

- [Errors](https://dev.virlo.ai/docs/errors): Error format (statusCode, code, message, error), the stable machine-readable "code" taxonomy for branching without string-matching messages, and common HTTP status codes
- [Webhooks](https://dev.virlo.ai/docs/webhooks): Real-time event notifications. Preferred: content_research_agent.run.completed (carries is_recurring; fires for both one-shot and recurring agents). Legacy/other events: orbit.run.completed, comet.run.completed, satellite.lookup.completed, tracking.cycle.completed, tracking.outlier_video.detected, tracking.paused, audience.snapshot.completed, trends.daily.completed (global), trends.region.completed (per-region: us/gb/au/…). Webhook management responses are not {data}-enveloped (bare array/object).
- [OpenAPI Spec](https://api.virlo.ai/openapi.json): Machine-readable OpenAPI 3.0 spec with full response schemas — use with openapi2mcp, RestMCP, or code generators