Make your first call
Authenticate a request to the Piloterr API and read the response.
Once you have a key, authentication is a single header. This page shows the shape of a request, how to confirm it worked, and what to do when it does not.
Response
{
"remaining": 42180,
"total_used": 57820,
"renewal_date": "2026-04-01"
}API Logs
Send the request
Pass your key in the x-api-key header on every call. The usage endpoint is free, which makes it the safest way to verify a new key:
curl "https://api.piloterr.com/v2/usage" \
-H "x-api-key: $API_KEY"const res = await fetch("https://api.piloterr.com/v2/usage", {
headers: { "x-api-key": process.env.API_KEY },
})
if (!res.ok) throw new Error(`Request failed: ${res.status}`)
const usage = await res.json()What a successful usage response looks like
A 200 from the usage endpoint means the key works. The JSON includes remaining (combined runway), subscription and credits balances, renewal_date when a period applies, and the api_key that made the call — including its quotas. None of that call costs credits.
If it does not work
| Response | Cause | Fix |
|---|---|---|
401 Invalid API Key | The header is missing or the value is wrong | Check for a trailing space or newline in the copied secret |
401 Inactive API Key | The key was deactivated | Reactivate it under API Keys, or create a new one |
401 Rate limit exceeded | A per-key quota or your plan's rate limit was hit | Slow down, or raise the limits on the key |
402 Payment required | No credits left, or an unpaid invoice | Add a top-up, enable auto top-up, or settle the invoice |
Set your HTTP client timeout to at least 60 seconds. Many platform defaults are far lower and abort the call before Piloterr has replied.