# Virlo API

> Short-form video intelligence for TikTok, YouTube Shorts, and Instagram Reels. Research a niche with Content Research Agents, look up creators, sounds, and hashtags, track creators and videos over time, and read daily trends, sounds, hooks, hashtags, and top videos.

- Base URL: `https://api.virlo.ai/v1`. Auth header: `Authorization: Bearer YOUR_API_KEY` (keys start with `virlo_tkn_`; get one at https://dev.virlo.ai/dashboard/api-keys).
- Responses are JSON inside a `data` field (except `/v1/webhooks`). Field names are snake_case.
- Prepaid US-dollar balance, no subscription. 1 credit = $0.01. The `X-Cost` header on each successful response is the exact charge; errors are free. Checking your balance (`GET /v1/account/balance`) is free.
- Slow jobs (agents, lookups) return an ID: check its status every 15 seconds, or whatever `retry_after_seconds` says, until `finalized` is `true`.
- Use Virlo from an AI assistant with the MCP server at https://dev.virlo.ai/api/mcp/mcp.
- Every page below is Markdown. All pages in one file: https://dev.virlo.ai/llms-full.txt. OpenAPI spec: https://api.virlo.ai/openapi.json.

## Start here

- [Introduction](https://dev.virlo.ai/docs.md): Research niches, look up creators, sounds, and hashtags, and follow trends on TikTok, YouTube Shorts, and Instagram Reels through the Virlo API.
- [Quickstart](https://dev.virlo.ai/docs/quickstart.md): Get an API key, check it works with a free request, then pull today's trends for $0.25.
- [Authentication](https://dev.virlo.ai/docs/authentication.md): How to get a Virlo API key, send it with each request, and fix a rejected key.
- [Billing and pricing](https://dev.virlo.ai/docs/credits.md): How Virlo API billing works: a prepaid dollar balance, pay per successful request, auto top-up, no subscriptions, and a free endpoint to check your balance.
- [Glossary](https://dev.virlo.ai/docs/glossary.md): Plain definitions of the words used in the Virlo API docs, including three that mean different things on different pages: outlier, weighted_score, and run.

## Content Research Agents

- [Overview](https://dev.virlo.ai/docs/agents.md): Research a niche once or on a schedule. One call creates the agent. After it runs, you read its videos, creators, trends, and analysis, almost all of it for free.
- [Autopilot](https://dev.virlo.ai/docs/agents/autopilot.md): After each run, a recurring Content Research Agent tunes its own keywords so it keeps finding new videos. Autopilot is on by default, never removes the keywords you set, and never adds charges.
- [Intent cookbook](https://dev.virlo.ai/docs/intent-cookbook.md): How to write the one-sentence intent that tells a Content Research Agent which videos to keep, with good and bad examples from real agents.
- [Data Intelligence](https://dev.virlo.ai/docs/intelligence.md): AI labels the videos a Content Research Agent collects with 79 fields: topic, hook, format, tone, brand safety, who is on screen, AI use and more. Off-topic, year-old and underperforming videos are skipped on purpose. Slideshows get 70. Costs $1.00 extra per run.

## Deep-dive lookups

- [Creator lookup](https://dev.virlo.ai/docs/satellite.md): Look up any creator on TikTok, YouTube Shorts, or Instagram. Start a lookup, get a job ID, then fetch their profile, stats, top hashtags, standout videos, and optional audience, trend analysis, and Data Intelligence add-ons.
- [Creator lookup add-ons](https://dev.virlo.ai/docs/satellite/creators.md): Two add-ons for a creator lookup. Trend analysis finds the formats and hooks a creator keeps repeating, with dates and momentum. Data Intelligence has AI break down every video.
- [Video outlier check](https://dev.virlo.ai/docs/satellite/video-outlier.md): Check whether one TikTok, YouTube or Instagram video beat its creator's usual views. Start a check for $0.50, then come back for an outlier score, a percentile and a plain label such as viral.
- [Sound lookup](https://dev.virlo.ai/docs/satellite/sounds.md): Pull a fresh sample of the videos using one TikTok or Instagram sound, with stats on views, creators, hashtags, and posting weeks. Add trend analysis to see the creative formats people make with it.
- [Hashtag lookup](https://dev.virlo.ai/docs/satellite/hashtags.md): Look up one hashtag on TikTok, Instagram, or YouTube Shorts and get a sample of the videos posted under it, with stats on views, creators, related hashtags, top sounds, and the weeks those videos were posted. Add optional trend analysis: the creative patterns in those videos.

## Tracking

- [Track creators and videos](https://dev.virlo.ai/docs/tracking.md): Watch a creator or a single video over time. Virlo re-checks it on your schedule, saves the numbers, and writes an AI report each time.

## Explore data

- [Trends](https://dev.virlo.ai/docs/trends.md): See which topics are trending on short-form video right now, worldwide or by country, with a momentum reading and example videos for each trend.
- [Sounds](https://dev.virlo.ai/docs/sounds.md): Find trending and breakout sounds, search sounds by title, look up one sound (its videos, daily usage, and the real song behind it), and list every sound credited to an artist or creator across TikTok, YouTube, and Instagram.
- [Hooks](https://dev.virlo.ai/docs/hooks.md): See which opening lines work on short-form video. Look up real hooks from about 1.4M TikTok, YouTube and Instagram posts with their views and Virality Score, find which hook types win in your niche, and browse 4,100+ hook templates.
- [Hashtags](https://dev.virlo.ai/docs/hashtags.md): The most-used and most-viewed hashtags in short-form video for any period of up to 90 days, plus video count, views, likes and comments for a single hashtag.
- [Videos](https://dev.virlo.ai/docs/videos.md): Get the most-viewed short videos posted in the last 48 hours across TikTok, YouTube Shorts, and Instagram Reels.

## By platform

- [YouTube hashtags](https://dev.virlo.ai/docs/youtube-hashtags.md): The most-used and most-viewed hashtags on YouTube Shorts for any period of up to 90 days. Works like the Hashtags top list, $0.05 per successful request.
- [YouTube videos](https://dev.virlo.ai/docs/youtube-videos.md): Get the most-viewed YouTube Shorts posted in the last 48 hours in one request.
- [TikTok hashtags](https://dev.virlo.ai/docs/tiktok-hashtags.md): The most-used and most-viewed hashtags on TikTok for any period of up to 90 days. Works like the Hashtags top list, $0.05 per successful request.
- [TikTok videos](https://dev.virlo.ai/docs/tiktok-videos.md): Get the most-viewed TikTok videos posted in the last 48 hours in one request.
- [Instagram hashtags](https://dev.virlo.ai/docs/instagram-hashtags.md): The most-used and most-viewed hashtags on Instagram Reels for any period of up to 90 days. Works like the Hashtags top list, $0.05 per successful request.
- [Instagram videos](https://dev.virlo.ai/docs/instagram-videos.md): Get the most-viewed Instagram Reels posted in the last 48 hours in one request.

## How the API works

- [How results load](https://dev.virlo.ai/docs/async-data.md): Some Virlo jobs keep working in the background after you start them. How to tell when the results are fully ready, and how to wait for them.
- [Pagination](https://dev.virlo.ai/docs/pagination.md): How to page through long lists in the Virlo API: which parameters each endpoint takes and how to tell when you have reached the last page.
- [Rate limits](https://dev.virlo.ai/docs/rate-limits.md): How many requests you can make, when limits reset, and what to do when you hit one.
- [Webhooks](https://dev.virlo.ai/docs/webhooks.md): Get a message at your own web address when an agent run, lookup, tracking check or trend update is done. Set up webhooks, check deliveries and resend failed ones.
- [Errors](https://dev.virlo.ai/docs/errors.md): What a Virlo API error looks like, what each error code means, and what to do about it.
- [Workflow recipes](https://dev.virlo.ai/docs/recipes.md): Step-by-step code for common research questions: what works in a niche, why a creator's video took off, what is trending, which hashtags are big, and what works in another language or country. Each recipe lists its cost and how long it takes.
- [API playground](https://dev.virlo.ai/docs/playground.md): Try every Virlo API endpoint and see real replies drawn as videos, creators, sounds and charts. No API key needed.

## For AI assistants

- [MCP server](https://dev.virlo.ai/docs/mcp.md): Connect Claude, Cursor, VS Code, Codex, Windsurf, or any other MCP app to Virlo. 55 tools for Content Research Agents, creator, video, sound and hashtag lookups, tracking, sounds, hooks, audience data, and trends.
- [Connect an AI assistant](https://dev.virlo.ai/docs/ai-agents.md): Connect Cursor, Claude, OpenClaw, and other AI assistants to Virlo with the MCP server, plain-text docs files, the ClawHub skill, or the OpenAPI spec.
- [Research playbook](https://dev.virlo.ai/docs/agent-playbook.md): How people and AI assistants pick the right Virlo workflow for a research question and read the results correctly: costs, timings, virality scoring, platform benchmarks, AI fields, and audience data.

## Optional

- [Orbit (one-time agents)](https://dev.virlo.ai/docs/orbit.md): Deprecated. Orbit is the old address for a one-time Content Research Agent. How to move from /v1/orbit to /v1/agents.
- [Comet (recurring agents)](https://dev.virlo.ai/docs/comet.md): Deprecated. Comet is the old name for a recurring Content Research Agent. How to move from /v1/comet to /v1/agents.
- [Research playbook as plain text](https://dev.virlo.ai/agent-playbook.txt): The same routing and interpretation guide the MCP server gives AI assistants.
- [OpenAPI specification](https://api.virlo.ai/openapi.json): Machine-readable request and response schemas.