API reference
Get usage
GET /api/v2/usage — your rate limit and scan allowance, and what is left of them.
Returns the limits that apply to the caller and how much of each remains. Use it to check your allowance before starting a batch, rather than finding out from a 429 halfway through.
GET /api/v2/usageThe answer is for the API key on the request. Without a valid key it is a 401.
This call counts as one request against your per-minute limit. It never counts as a scan.
Example
curl -s https://carbonfooter.nl/api/v2/usage \
-H 'Authorization: Bearer cf_live_…'Response
{
"version": "2.0",
"tier": "key",
"key": { "prefix": "cf_live_a1b2", "label": "Acme agency" },
"requests": { "limit": 60, "remaining": 59, "resetsAt": "2026-11-10T12:01:00.000Z" },
"scans": {
"limit": 1000,
"used": 112,
"remaining": 888,
"period": "month",
"resetsAt": "2026-12-01T00:00:00.000Z"
}
}interface UsageResponse {
version: '2.0'
/** Always `key`: the API requires one. */
tier: 'key'
/** The key the request was made with; never the key itself. */
key: { prefix: string; label: string }
/** All requests, per minute. */
requests: {
limit: number | null
remaining: number | null
resetsAt: string
}
/** New scans only — a result served from cache is never counted. */
scans: {
limit: number | null
used: number
remaining: number | null
/** Per calendar month (UTC). */
period: 'month'
resetsAt: string
}
}A null limit, with a null remaining, means unlimited.
Errors
| Status | error.code | When |
|---|---|---|
401 | UNAUTHORIZED | No API key was sent, or it is invalid or revoked |
429 | RATE_LIMITED | Too many requests this minute |
500 | INTERNAL | Unexpected server error |
Related
- Authentication — keys, tiers and what counts as a scan
- Errors