Authentication
Every /v1 route needs an API key. Create keys in the console; each is shown once, and only a hash is stored.
Sending the key
Section titled “Sending the key”| Where | Example | Use for |
|---|---|---|
Authorization header |
Authorization: Bearer vtx_live_… |
Servers, scripts, agents. Preferred. |
x-api-key header |
x-api-key: vtx_live_… |
Clients that can’t set Authorization. |
apikey query parameter |
…/{z}/{x}/{y}.png?apikey=vtx_live_… |
Tile templates that a map SDK fetches itself. |
Keys start with vtx_live_. Treat them as secrets: a key in a public web page can be copied. For browser maps, put the tile template behind your own proxy, or accept that a free-plan key exposes at most its own daily cap.
| Plan | Credits | Burst | Keys |
|---|---|---|---|
| Free | 15,000 a month, 1,000 a day | 10 requests/s | 1 |
| Pay as you go | Uncapped; a monthly spend cap you set | 50 requests/s | Unlimited |
| Enterprise | Custom | Custom | Custom |
Plans are per account and apply to every key on it. See Pricing and credits.
Response headers
Section titled “Response headers”| Header | Meaning |
|---|---|
x-credits-cost |
Credits this request consumed. 0 on 4xx/5xx responses. |
x-credits-remaining |
Credits left this month (free plan). |
x-credits-daily-remaining |
Credits left today (free plan). |
x-spend-remaining-usd |
Dollars left before the spend cap (pay as you go). |
ratelimit-limit |
Requests allowed per 10-second window. |
x-vertex-plan |
The key’s plan. |
Errors
Section titled “Errors”| Status | Body | What to do |
|---|---|---|
401 |
unauthorized: missing or invalid API key |
Check the key and where you send it. Revoked keys stop working within a minute. |
402 |
{"error":"quota_exceeded","scope":"daily"|"monthly"|"spend_cap","resets_at":"…"} |
Wait for resets_at, raise your spend cap, or upgrade. |
429 |
{"error":"rate_limited","retry_after_s":10} |
Back off for the window. |
400 |
{"detail":"…"} |
A parameter problem; the detail says which. |
503 |
{"detail":"no data yet for model 'x'"} |
The model’s current run is mid-publish. Retry in a minute. |
Only successful responses are billed. A 4xx or 5xx refunds its charge.
GET /v1/usage returns the calling key’s counters, free of charge:
{ "key": "production", "plan": "free", "metered": true, "period": { "month": "2026-09", "day": "2026-09-19", "month_resets_at": "2026-10-01T00:00:00.000Z", "day_resets_at": "2026-09-20T00:00:00.000Z" }, "credits": { "month": 412.4, "today": 61.2, "by_product": { "forecast": 380, "tile": 32.4 }, "requests_this_month": 542 }, "caps": { "daily_credits": 1000, "monthly_credits": 15000, "spend_usd": null }, "remaining": { "today": 938.8, "month": 14587.6, "spend_usd": null }, "month_usd": 0}Periods are UTC calendar days and months.