API Key Usage

Query how much a given API key spent over a period of time. To make a request, you only need your AIMLAPI key obtained from your account dashboard.

Both endpoints take the same parameters and differ only in what they return: /v2/usage/detail adds a per-model breakdown.

Choosing the time window

Pass either period or both start and end — not both at once:

• period is relative — 24h, 7d, that is a positive integer followed by h or d.

• start and end are absolute ISO-8601 timestamps.

The window cannot exceed 92 days. For a longer report, request several windows and add them up.

A timestamp without a UTC offset is read as UTC, not as your local time. Pass an explicit offset (2026-07-01T00:00:00+03:00) if you mean something else.

The response always echoes start and end resolved to UTC, so you can see exactly which window was measured.

Choosing the key

Your key	key_prefix	Result
any key	omitted	its own spend
management key	provided	that key's spend
regular key	provided, its own prefix	its own spend
regular key	provided, another prefix	403

Any key can read its own spend. Reading the spend of a different key requires a management key.

Get key usage

Returns the total spend for a key over the requested window.

get

Query parameters

periodstringOptional

Relative window: a positive integer followed by h or d, for example 24h or 7d. Provide either period or both start and end, never both.

Example: 24h

startstringOptional

Window start, ISO-8601. A value without a UTC offset is read as UTC. Must be used together with end.

Example: 2026-07-01T00:00:00Z

endstringOptional

Window end, ISO-8601. Must not be earlier than start, and the window must not exceed 92 days.

Example: 2026-07-28T00:00:00Z

key_prefixstringOptional

Prefix of the key to report on. Omit it to get the spend of the key you are authenticating with. Reporting on a different key requires a management key.

Example: abcd1234

Responses

200

Total spend for the key over the requested window.

application/json

api_key_prefixstring · nullableRequired

The requested key prefix, or null when it was omitted and the answer is your own key's spend.

Example: abcd1234

startstringRequired

Window start, resolved to UTC.

Example: 2026-07-26T22:15:00.000Z

endstringRequired

Window end, resolved to UTC.

Example: 2026-07-27T22:15:00.000Z

spendnumberRequired

Total spend for the key over the window, in USD.

Example: 13.704199

currencystringRequired

Spend currency (always USD).

Example: USD

requestsintegerRequired

Number of charged requests in the window.

Example: 9643

get/v2/usage

curl -L \
  --request GET \
  --url 'https://api.aimlapi.com/v2/usage?period=24h' \
  --header 'Authorization: Bearer <YOUR_AIMLAPI_KEY>'

200

Total spend for the key over the requested window.

{
  "api_key_prefix": "abcd1234",
  "start": "2026-07-26T22:15:00.000Z",
  "end": "2026-07-27T22:15:00.000Z",
  "spend": 13.704199,
  "currency": "USD",
  "requests": 9643
}

Get detailed key usage

Returns the same total plus a per-model breakdown, sorted by spend.

get

Query parameters

periodstringOptional

Relative window: a positive integer followed by h or d, for example 24h or 7d. Provide either period or both start and end, never both.

Example: 7d

startstringOptional

Window start, ISO-8601. A value without a UTC offset is read as UTC. Must be used together with end.

Example: 2026-07-01T00:00:00Z

endstringOptional

Window end, ISO-8601. Must not be earlier than start, and the window must not exceed 92 days.

Example: 2026-07-28T00:00:00Z

key_prefixstringOptional

Prefix of the key to report on. Omit it to get the spend of the key you are authenticating with. Reporting on a different key requires a management key.

Example: abcd1234

Responses

200

Total spend for the key over the requested window, with a per-model breakdown.

application/json

api_key_prefixstring · nullableRequired

The requested key prefix, or null when it was omitted and the answer is your own key's spend.

Example: abcd1234

startstringRequired

Window start, resolved to UTC.

Example: 2026-07-20T22:15:00.000Z

endstringRequired

Window end, resolved to UTC.

Example: 2026-07-27T22:15:00.000Z

spendnumberRequired

Total spend for the key over the window, in USD. This is the authoritative total: it is computed from the total, not by adding up models, so it can differ from that sum by a few nano-dollars.

Example: 12.3456

currencystringRequired

Spend currency (always USD).

Example: USD

requestsintegerRequired

Number of charged requests in the window.

Example: 842

get/v2/usage/detail

curl -L \
  --request GET \
  --url 'https://api.aimlapi.com/v2/usage/detail?key_prefix=abcd1234&period=7d' \
  --header 'Authorization: Bearer <YOUR_AIMLAPI_MANAGEMENT_KEY>'

200

Total spend for the key over the requested window, with a per-model breakdown.

{
  "api_key_prefix": "abcd1234",
  "start": "2026-07-20T22:15:00.000Z",
  "end": "2026-07-27T22:15:00.000Z",
  "spend": 12.3456,
  "currency": "USD",
  "requests": 842,
  "models": [
    {
      "model": "openai/gpt-5",
      "spend": 8.12,
      "requests": 500
    }
  ]
}