Authentication

Every request must carry three headers:

Header	Value
`X-Api-Token`	Your API key
`X-Api-Version`	`v1`, the current version
`User-Agent`	A non-empty name for your integration, such as `my-integration/1.0`

Getting your API key

Generate your key in the dashboard, under Analytics API. The key identifies your company: every query only sees the players and data of that company.

Treat the key like a password. Keep it on your server, read it from an environment variable, and never commit it or send it to a browser. If it leaks, generate a new one in the dashboard.

Checking your credentials

GET /quota/usage takes no parameters, which makes it a good first call:

curl 'https://analytics.vturb.com/quota/usage' \
  -H "X-Api-Token: $VTURB_API_TOKEN" \
  -H 'X-Api-Version: v1' \
  -H 'User-Agent: my-integration/1.0'

A 200 means the key works. The JavaScript sample runs on Node.js 18 or later, on your server.

Sending a query

Queries are POST requests with a JSON body, sent with the same three headers plus Content-Type:

curl -X POST 'https://analytics.vturb.com/conversions/active_platforms' \
  -H "X-Api-Token: $VTURB_API_TOKEN" \
  -H 'X-Api-Version: v1' \
  -H 'User-Agent: my-integration/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "start_date": "2026-09-01 00:00:00",
    "timezone": "America/Sao_Paulo"
  }'

Authentication errors

Status	Response	Cause
`401`	`{"error":"missing token"}`	`X-Api-Token` is missing or empty
`401`	`{"error":"invalid credentials"}`	The key does not exist, or the account cannot use the API
`401`	`{"error":"...","code":516}`	The company does not have access to the Analytics API
`401`	`{"error":"...","code":241}`	The plan of the key does not allow this query
`403`	HTML page	`User-Agent` is missing or empty
`404`	`{"error_msg":"404 Route Not Found"}`	`X-Api-Version` is missing or is not `v1`

The 403 and the 404 come from the edge, before the request reaches the API, so their bodies are not JSON errors from the API.

Best practices

Send the same descriptive User-Agent from every part of your integration; it is how we tell your traffic apart when you ask for support.
Retry 429 after resets_at, and 503 after a short wait with exponential backoff. Do not retry 400, 401, 403 or 404: they will fail the same way until the request changes.
Log the status and body of failed requests. They are what support will ask for.

If you still cannot authenticate, contact our support at help.vturb.com.