# Quickstart

> Get an API key, check it works with a free request, then pull today's trends for $0.25.

Source: https://dev.virlo.ai/docs/quickstart
Markdown: https://dev.virlo.ai/docs/quickstart.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.

---

Check your API key with a free request, then pull today's top trends.

**At a glance**

- **What it does:** Gets you from sign-up to your first results.
- **You send:** Two requests with your API key.
- **You get back:** Your balance, then today's top trends.
- **Cost:** $0.25 total. The balance check is free.

## Before you start

Someone gave you a key? Skip steps 1 to 3.

1. **Create an account** at [dev.virlo.ai/signup](https://dev.virlo.ai/signup).
2. **Add funds** on the [Billing page](https://dev.virlo.ai/dashboard/billing). You need a balance to generate a key.
3. Click **Generate Key** on the [API keys](https://dev.virlo.ai/dashboard/api-keys) page and copy the key. It is shown only once.

Paste your whole key over `YOUR_API_KEY`; it already starts with `virlo_tkn_`. Mac: cURL tab in Terminal. Windows: the **Windows** tab here, in PowerShell. For cURL examples on other pages, use Git Bash.

Rather not use a terminal? Once you have a key, pick **Trends Digest** in the [dashboard playground](https://dev.virlo.ai/dashboard/playground). Same request, same $0.25.

## Check your balance

This free call tests your key. If you see your balance, it works.

**cURL request:**

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

**Windows request:**

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

**JavaScript request:**

```js
async function main() {
  const response = await fetch('https://api.virlo.ai/v1/account/balance', {
    headers: { Authorization: 'Bearer YOUR_API_KEY' },
  })
  console.log(response.status, await response.json())
}

main()
```

**Python request:**

```python
import requests

response = requests.get(
    'https://api.virlo.ai/v1/account/balance',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
)
print(response.status_code, response.json())
```

**Response 200 It worked:**

```json
{
  "data": {
    "balance": "$25.00",
    "credits_remaining": 2500,
    "status": "active"
  }
}
```

**Response 401 Bad key:**

```json
{
  "message": "Invalid or inactive API key",
  "error": "Unauthorized",
  "statusCode": 401,
  "code": "invalid_api_key"
}
```

`balance` is in dollars; `credits_remaining` is the same in credits (1 credit = $0.01). A `401` means the key is missing, mistyped, or revoked: see [Authentication](https://dev.virlo.ai/docs/authentication#when-a-key-is-rejected).

## Get today's trends

Returns today's top worldwide trends, ranked, in about a second. **It costs $0.25 each time.** Under $0.25 left? You get an `insufficient_credits` error.

**cURL request:**

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

**Windows request:**

```powershell
curl.exe https://api.virlo.ai/v1/trends/digest -H "Authorization: Bearer YOUR_API_KEY"
```

**JavaScript request:**

```js
async function main() {
  const response = await fetch('https://api.virlo.ai/v1/trends/digest', {
    headers: { Authorization: 'Bearer YOUR_API_KEY' },
  })
  const body = await response.json()
  if (!response.ok) return console.error(response.status, body.message)

  console.log('Cost: $' + response.headers.get('X-Cost'))
  for (const group of body.data) {
    console.log(group.title)
    for (const item of group.trends) {
      console.log(item.ranking, item.trend.name)
    }
  }
}

main()
```

**Python request:**

```python
import requests

response = requests.get(
    'https://api.virlo.ai/v1/trends/digest',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
)
response.raise_for_status()

print('Cost: $' + response.headers['X-Cost'])
for group in response.json()['data']:
    print(group['title'])
    for item in group['trends']:
        print(item['ranking'], item['trend']['name'])
```

**Response 200 It worked:**

```json
{
  "data": [
    {
      "id": "0a3dd8f0-7bb2-4de0-a7e2-74eb82d851ae",
      "title": "Trends for Sep 24",
      "region": "global",
      "local_date": "2026-09-24",
      "trends": [
        {
          "ranking": 1,
          "trend": {
            "id": "503b791b-663a-4ae0-bccc-6d3329707f1e",
            "name": "Meta's new VR glasses lineup (Ray-Ban Audio + no camera + 5K micro OLED visuals) & Meta Connect 2026 reveals",
            "description": "On September 23, 2026, Meta unveiled its latest VR wearables at the Meta Connect conference, including the Ray-Ban Meta Audio glasses, which lack a camera and focus on audio capabilities, and the advanced Meta VR Glasses featuring 5K micro-OLED visuals."
          },
          "momentum": {
            "status": "new",
            "views_per_hour": 131006
          },
          "top_exemplars": [
            {
              "url": "https://www.youtube.com/shorts/p4BUXLcRvKk",
              "platform": "youtube",
              "views": 3660687,
              "author": {
                "username": "@actuallycarterpcs"
              }
            }
          ]
        }
      ]
    }
  ]
}
```

- `data`: one daily list of 15 to 20 topics, up to 5 example videos each.
- A new worldwide list starts at 7:00 New York time; trends are added at 13:00 and 19:00. Before 7:00 you get yesterday's, even if `title` says today; check `local_date`.
- `momentum.status` is `new`, `rising`, `steady`, or `fading` (`momentum` is `null` until measured).
- `top_exemplars` are sorted by all-time views, so older videos can appear.

Add `?region=us` for one country (or `gb`, `au`, `sg`), or `?top_exemplars=0` for a shorter reply. See [Trends](https://dev.virlo.ai/docs/trends).

### See what you paid

To see the charge, add `-i` after `curl`. Look for these (curl may print them in lowercase):

**Response headers:**

```http
X-Cost: 0.25
X-Credits-Used: 25
X-Balance-Remaining: 24.75
X-Credits-Remaining: 2475
```

- `X-Cost` is the charge in dollars, with no `$`. Free calls show `0.00`.
- `X-Balance-Remaining` is your balance afterward; the `Credits` headers repeat both in credits.
- `Remaining` headers can appear on free calls too (never on the balance check), so only `X-Cost` shows what you paid.
- Failed requests are never charged and carry none of these headers.

## What's next?

- [Content Research Agents](https://dev.virlo.ai/docs/agents): research a niche once or on a schedule.
- [Billing and pricing](https://dev.virlo.ai/docs/credits): what each request costs.
- [Errors](https://dev.virlo.ai/docs/errors): what each error `code` means.
- [MCP server](https://dev.virlo.ai/docs/mcp): use Virlo from Claude, Cursor, or VS Code.
- [Research playbook](https://dev.virlo.ai/docs/agent-playbook): which workflow fits which question.

---

More in Start here:

- [Introduction](https://dev.virlo.ai/docs.md)
- [Authentication](https://dev.virlo.ai/docs/authentication.md)
- [Billing and pricing](https://dev.virlo.ai/docs/credits.md)
- [Glossary](https://dev.virlo.ai/docs/glossary.md)