# Billing and pricing

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

Source: https://dev.virlo.ai/docs/credits
Markdown: https://dev.virlo.ai/docs/credits.md
Section: Start here

## About the Virlo API (applies to every page)

- Base URL: `https://api.virlo.ai/v1`. Every request needs the header `Authorization: Bearer YOUR_API_KEY` (keys start with `virlo_tkn_`).
- Responses are JSON inside a `data` field, except the `/v1/webhooks` endpoints, which return the object or array directly. Field names are snake_case.
- Prices are in US dollars from a prepaid balance. 1 credit = $0.01. The `X-Cost` response header on each successful response is the exact charge. Errors are free.
- Slow jobs return an ID. Check its status every 15 seconds (or whatever `retry_after_seconds` says) until `finalized` is `true`.
- All docs pages: https://dev.virlo.ai/llms.txt. Every page in one file: https://dev.virlo.ai/llms-full.txt. MCP server for AI assistants: https://dev.virlo.ai/api/mcp/mcp.

---

You pay from a prepaid dollar balance your team shares. No subscription, and the balance never expires.

**At a glance**

- **What it does:** Explains how you pay for the API.
- **You send:** Nothing extra. Paid requests take their price from your balance.
- **You get back:** Each successful reply shows its dollar price (`X-Cost` header).
- **Cost:** Checking your balance and re-reading results you paid for are free.

## How it works

1. Add funds on the [Billing page](https://dev.virlo.ai/dashboard/billing), which shows the minimum.
2. You pay for each accepted request, even if it finds nothing. Rejected requests (errors) are free, and so is a request whose reply never reaches you (it timed out or your connection closed first). A one-time agent is charged even if its run fails. A creator, sound, or hashtag lookup that fails (for example, the handle doesn't exist) is refunded later, as is a post collection that finds nothing.
3. Optional: turn on **auto top-up** in [Settings](https://dev.virlo.ai/dashboard/settings) to refill from your card when you run low.

## Scheduled charges

- **Recurring agents:** free to create, then $0.50 per run ($1.50 with [Data Intelligence](https://dev.virlo.ai/docs/credits#data-intelligence-add-ons)). The first run starts right away, so your balance must cover it.
- **[Tracking](https://dev.virlo.ai/docs/tracking):** $0.25 to start (covers the first check), then $0.25 per check. Asking for a creator's older posts (`collection_depth`) adds a one-time $0.50, $1.00, or $2.00.

Runs and later checks never show up in `X-Cost`. See each one on the [Usage](https://dev.virlo.ai/dashboard/usage) page, or [check your balance](https://dev.virlo.ai/docs/credits#check-your-balance) for free.

If your balance runs out, these pause, and adding funds won't restart them. To resume, set `active: true` with [Update agent](https://dev.virlo.ai/docs/agents#update-agent), or `status: active` with [Update tracking](https://dev.virlo.ai/docs/tracking#update-tracked-creator).

## Check your balance

**Endpoint:** `GET https://api.virlo.ai/v1/account/balance`

Returns your team's balance. Free.

**cURL request:**

```bash
curl https://api.virlo.ai/v1/account/balance \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**JavaScript request:**

```js
const res = await fetch('https://api.virlo.ai/v1/account/balance', {
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
})
const { data } = await res.json()
```

**Python request:**

```python
import requests

res = requests.get(
    'https://api.virlo.ai/v1/account/balance',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
)
data = res.json()['data']
```

**Response 200 OK:**

```json
{
  "data": {
    "balance": "$259.25",
    "credits_remaining": 25925,
    "status": "active"
  }
}
```

- `balance` (string, optional): Your balance in dollars.
- `credits_remaining` (integer, optional): The same balance in credits (1 credit = $0.01).
- `status` (string, optional): `active`, or `zero_balance` once it runs out.

## Prices

| Task | Price |
| - | - |
| [Content Research Agent](https://dev.virlo.ai/docs/agents) run | $0.50, $1.50 with Data Intelligence |
| [Creator lookup](https://dev.virlo.ai/docs/satellite) | $0.50, up to $1.75 with add-ons |
| [Sound lookup](https://dev.virlo.ai/docs/satellite/sounds) | $0.50, up to $1.00 |
| [Hashtag lookup](https://dev.virlo.ai/docs/satellite/hashtags) | $0.50, up to $2.50 |
| Pop culture & News, digests, trending sounds and hooks | $0.25 |
| [Content Trends](https://dev.virlo.ai/docs/content-trends) list | $0.25 |
| [One content trend](https://dev.virlo.ai/docs/content-trends#get-content-trend) | $0.05 |
| [Hashtag stats](https://dev.virlo.ai/docs/hashtags), [sound search](https://dev.virlo.ai/docs/sounds#search-sounds), [hook library](https://dev.virlo.ai/docs/hooks#hook-template-library) | $0.05 to $0.10 |

Full list below.

| Endpoint | Method | Price per request | What it does |
| - | - | - | - |
| `/v1/agents` | POST | $0.50 / run | Create a Content Research Agent. A one-time agent (is_recurring=false) is charged once, when you create it. A recurring agent (is_recurring=true) is free to create and charged after each run. Listing agents and reading results are free. |
| `/v1/tracking/creators/:id/posts` | ALL | Free | A tracked creator's posts, with numbers for each |
| `/v1/tracking/creators/:id/posts/:post_id` | ALL | Free | One post from a tracked creator |
| `/v1/tracking/creators/:id/posts/collect` | ALL | $0.50 to $2.00 | Collect a tracked creator's older posts (price depends on depth). Refunded if no posts are found. |
| `/v1/tracking/creators/:id/posts/collect/:collection_id` | ALL | Free | Check a post collection's status |
| `/v1/tracking/creators/:id/posting-cadence` | ALL | Free | How often a tracked creator posts |
| `/v1/satellite/creators/batch` | ALL | $0.50 / creator | Batch creator lookup (up to 25 creators). A creator looked up in the last 6 hours with at least the same options comes back from cache, free. |
| `/v1/satellite/creators/batch/:batch_id` | ALL | Free | Check a batch lookup's status |
| `/v1/tracking/creators/:id/audience-demographics` | ALL | Free | A tracked creator's audience by age and gender |
| `/v1/tracking/creators/:id/audience-geography` | ALL | Free | A tracked creator's audience by country |
| `/v1/tracking/creators/:id/audience-refresh` | ALL | $0.50 | Make a new audience snapshot for a tracked creator. Free on a cache hit, or while a snapshot is already being built. |
| `/v1/tracking/creators/:id/audience-refresh/:jobId` | ALL | Free | Check an audience snapshot's status |
| `/v1/satellite/sounds/status/:job_id` | GET | Free | Check a sound lookup's status |
| `/v1/satellite/runs/:run_id` | GET | Free | Re-read a saved lookup |
| `/v1/satellite/runs` | GET | Free | List your saved lookups (runs) |
| `/v1/satellite/runs/:run_id/videos` | GET | Free | Page through a saved lookup's videos |
| `/v1/hooks/types` | GET | Free | Which hook types win most often (free) |
| `/v1/tracking/creators/:id` | ALL | Free | Get, update, or stop tracking a creator |
| `/v1/tracking/creators/:id/report` | ALL | Free | A tracked creator's latest AI report |
| `/v1/tracking/creators/:id/snapshots` | ALL | Free | A tracked creator's numbers at each check |
| `/v1/tracking/videos/:id` | ALL | Free | Get, update, or stop tracking a video |
| `/v1/tracking/videos/:id/report` | ALL | Free | A tracked video's latest AI report |
| `/v1/tracking/videos/:id/snapshots` | ALL | Free | A tracked video's numbers at each check |
| `/v1/satellite/hashtags/status/:job_id` | GET | Free | Check a hashtag lookup's status |
| `/v1/hooks/library/categories` | GET | Free | Hook template categories (free) |
| `/v1/raw/:platform/creator/:handle` | GET | $0.01 | A creator's live profile and counts |
| `/v1/raw/:platform/video/comments` | GET | $0.01 | Live comments on a video: one page. Charged per page, even when empty. |
| `/v1/raw/:platform/hashtag/:hashtag` | GET | $0.01 | Live videos under a hashtag: one page. Charged per page, even when empty. |
| `/v1/raw/:platform/video/transcript` | GET | $0.01 | A TikTok or YouTube video's transcript |
| `/v1/raw/:platform/creator/:handle/videos` | GET | $0.01 | A creator's videos, live: one page. Charged per page, even when empty. |
| `/v1/raw/:platform/search` | GET | $0.01 | Live keyword search: one page of TikTok videos, YouTube Shorts or Instagram Reels. Charged per page, even when empty. |
| `/v1/raw/:platform/video` | GET | $0.01 | One video's live details and counts |
| `/v1/instagram/hashtags` | ALL | $0.05 | Top Instagram Reels hashtags for a date range |
| `/v1/tiktok/hashtags` | ALL | $0.05 | Top TikTok hashtags for a date range |
| `/v1/youtube/hashtags` | ALL | $0.05 | Top YouTube Shorts hashtags for a date range |
| `/v1/hashtags` | ALL | $0.05 | Top hashtags across all platforms for a date range |
| `/v1/content-trends/:id` | GET | $0.05 | One content trend with all its example videos and 30-day history |
| `/v1/sounds/:sound_id` | GET | $0.05 | One sound's details. Matching it to a song (resolve=true) adds $0.10 the first time. |
| `/v1/sounds/:sound_id/usage-history` | GET | $0.05 | A sound's daily usage history |
| `/v1/hashtags/:hashtag/performance` | ALL | $0.05 | One hashtag's video count and views |
| `/v1/sounds/search` | GET | $0.10 | Search sounds by title |
| `/v1/hooks/library` | GET | $0.10 | Hook templates, with why each one works |
| `/v1/hooks/trending` | GET | $0.25 | Top hooks from recent posts |
| `/v1/content-trends` | GET | $0.25 | Content Trends: video formats creators are copying, reviewed by Virlo |
| `/v1/hooks/search` | GET | $0.25 | Search about 1.4 million hooks by phrase or type |
| `/v1/agents/:id/hooks` | GET | $0.25 | Top hooks from an agent's videos. Free when the agent has Data Intelligence, or while it has no hooks yet. |
| `/v1/tiktok/videos/digest` | ALL | $0.25 | Most-viewed TikToks from the last 48 hours |
| `/v1/tracking/creators` | POST | $0.25 | Start tracking a creator. The price covers the first check, and each later check costs the same. |
| `/v1/instagram/videos/digest` | ALL | $0.25 | Most-viewed Instagram Reels from the last 48 hours |
| `/v1/trends` | ALL | $0.25 | Pop culture & News: daily lists for a date range |
| `/v1/trends/digest` | ALL | $0.25 | Pop culture & News: today's list for a region |
| `/v1/tracking/videos` | POST | $0.25 | Start tracking a video. The price covers the first check, and each later check costs the same. |
| `/v1/sounds/breakout` | GET | $0.25 | Sounds growing fastest from a small start |
| `/v1/sounds/trending` | GET | $0.25 | Trending sounds |
| `/v1/sounds/:sound_id/videos` | GET | $0.25 | Videos that use a sound |
| `/v1/sounds/by-creator/:platform/:handle` | GET | $0.25 | Sounds a creator owns |
| `/v1/youtube/videos/digest` | ALL | $0.25 | Most-viewed YouTube Shorts from the last 48 hours |
| `/v1/videos/digest` | ALL | $0.25 | Most-viewed videos from the last 48 hours, all platforms |
| `/v1/trends/emerging` | ALL | $0.25 | Pop culture & News that are new or rising right now |
| `/v1/satellite/hashtags/:platform/:hashtag` | GET | $0.50 | Hashtag lookup: stats, trends, and videos for one hashtag. Refunded in full if the lookup fails. |
| `/v1/satellite/sounds/:platform/:music_id` | GET | $0.50 | Sound lookup (runs in the background). Refunded in full if the lookup fails. |
| `/v1/satellite/creator/:platform/:username` | ALL | $0.50 | Creator lookup (runs in the background). Refunded in full if the lookup fails. |
| `/v1/satellite/video-outlier` | POST | $0.50 | Video outlier check (runs in the background) |

**Optional add-ons (charged on top of the base price)**

| Add-on | Cost | Applies to |
| - | - | - |
| Data Intelligence for agents | +$1.00 per run | data_intelligence_enabled=true on a Content Research Agent. An AI breakdown of every video (79 fields; slideshows get 70). One-time and recurring agents cost the same, and a recurring agent is charged once per run. It cannot be added to a run that already happened. |
| Trend analysis | +$0.50 per lookup | trend_analysis=true on a creator, sound, or hashtag lookup. Reads up to about 300 videos and returns the patterns it finds in a trends block. Refunded when no trends come out (fewer than 10 videos, or the analysis step failed). |
| Data Intelligence for creator lookups | +$0.25 per lookup | data_intelligence=true on a creator lookup. Adds each video's hook, content format, and visual style (43 fields; 35 for a photo carousel), plus a "what's working" summary. Read it on GET /v1/satellite/runs/:run_id. Refunded when there are no posts to enrich, the analysis fails, or the whole lookup fails. |
| Hashtag depth: deep | +$0.50 per lookup | depth=deep (about 300 videos) on a hashtag lookup. Not charged when trend_analysis=true, which already collects that many. |
| Hashtag depth: full | +$1.50 per lookup | depth=full (about 500 videos) on a hashtag lookup. |
| Audience snapshot | +$0.50 per creator | audience_demographics or audience_geography on a creator lookup or batch lookup, or POST /v1/tracking/creators/:id/audience-refresh. Free when a snapshot from the last 30 days already exists or one is already being built. Refunded when the snapshot fails. |

## Data Intelligence add-ons

An AI breakdown of each video:

- **Agents:** `data_intelligence_enabled: true` adds $1.00 per run ([details](https://dev.virlo.ai/docs/intelligence)). On a recurring agent, [turning it on or off later](https://dev.virlo.ai/docs/agents#update-agent) affects only future runs.
- **Creator lookups:** `data_intelligence=true` adds $0.25, so a lookup costs $0.75. You get each video's hook, content format, and visual style, plus a summary of what's working.

## Response headers

Only successful responses carry these. Amounts have no `$` sign.

- `X-Cost`: the exact charge in dollars (`0.00` if free). `X-Credits-Used` gives it in credits.
- `X-Balance-Remaining`: your balance afterward, on endpoints that can charge, even when this call was free. Only `X-Cost` shows your charge. `X-Credits-Remaining` gives the balance in credits.

## Insufficient balance

If your balance can't cover a request, you get a `402` and aren't charged. Messages vary, so read `code`, `required_credits` (price), and `remaining_credits` (balance), both in cents.

**Most endpoints:**

```json
{
  "statusCode": 402,
  "message": "Insufficient balance. $0.25 required, $0.12 remaining. Add funds at https://dev.virlo.ai/dashboard/billing",
  "error": "Payment Required",
  "required_credits": 25,
  "remaining_credits": 12,
  "required_amount": "$0.25",
  "remaining_balance": "$0.12",
  "code": "insufficient_credits"
}
```

**Creating an agent:**

```json
{
  "statusCode": 402,
  "code": "insufficient_credits",
  "message": "Insufficient credits",
  "error": "Payment Required",
  "required_credits": 50,
  "remaining_credits": 12
}
```

On auto top-up? The card charge may have failed, so check [Billing](https://dev.virlo.ai/dashboard/billing). A `429` means too many requests, not low funds ([Rate limits](https://dev.virlo.ai/docs/rate-limits)).

---

More in Start here:

- [Introduction](https://dev.virlo.ai/docs.md)
- [Quickstart](https://dev.virlo.ai/docs/quickstart.md)
- [Authentication](https://dev.virlo.ai/docs/authentication.md)
- [Glossary](https://dev.virlo.ai/docs/glossary.md)