Skip to Content
CarbonFooterv2.0
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/usage

The 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

Terminal
curl -s https://carbonfooter.nl/api/v2/usage \
  -H 'Authorization: Bearer cf_live_…'

Response

200 — with a key
{
  "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"
  }
}
Types
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

Statuserror.codeWhen
401UNAUTHORIZEDNo API key was sent, or it is invalid or revoked
429RATE_LIMITEDToo many requests this minute
500INTERNALUnexpected server error

On this page