> For the complete documentation index, see [llms.txt](https://docs.aimlapi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aimlapi.com/api-references/service-endpoints/api-key-usage.md).

# 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](https://aimlapi.com/app/keys).

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.

{% hint style="info" %}
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.
{% endhint %}

## 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.

## Grouping the breakdown

`/v2/usage/detail` can additionally split the window into buckets. Pass `group_by`:

| Value       | Adds one entry per…      |
| ----------- | ------------------------ |
| `day`       | day in the window        |
| `model`     | model used in the window |
| `day,model` | model per day            |

```bash
curl -H 'Authorization: Bearer <YOUR_AIMLAPI_KEY>' \
  'https://api.aimlapi.com/v2/usage/detail?period=30d&group_by=day,model&tz=Europe/Berlin'
```

Each entry in the resulting `groups` array carries its `spend`, `tokens` and a `requests` object. Omitting `group_by` leaves the response exactly as it was.

`tz` sets where the day boundary falls; it defaults to UTC and only affects `group_by=day`. The top-level `start` and `end` stay UTC regardless.

{% hint style="warning" %}
**Reconcile against `requests.charged`, not `requests.total`.**

A failed request is billed nothing — the hold is rolled back — so it has no charge behind it. `requests.total` counts every request in the group, `requests.charged` only the billed ones, and the top-level `requests` is the charged count. So `requests` equals the sum of `groups[].requests.charged`, and it matches the sum of `groups[].requests.total` only in a window where nothing failed.
{% endhint %}

{% hint style="info" %}
`tz` must be a **canonical IANA zone name matched exactly** — `Europe/Berlin`, `UTC`. Offset forms (`+05:00`) and other-case spellings (`utc`) are rejected with `400`.

`group_by` and `tz` are accepted on `/v2/usage/detail` only. A flat total has nowhere to put a breakdown, so `/v2/usage` answers `400` rather than silently ignoring them.
{% endhint %}

## Get key usage

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

## GET /v2/usage

>

```json
{"openapi":"3.0.0","info":{"title":"AIML API","version":"1.0.0"},"servers":[{"url":"https://api.aimlapi.com"}],"paths":{"/v2/usage":{"get":{"operationId":"_v2_usage","parameters":[{"name":"period","in":"query","required":false,"description":"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.","schema":{"type":"string"}},{"name":"start","in":"query","required":false,"description":"Window start, ISO-8601. A value without a UTC offset is read as UTC. Must be used together with `end`.","schema":{"type":"string"}},{"name":"end","in":"query","required":false,"description":"Window end, ISO-8601. Must not be earlier than `start`, and the window must not exceed 92 days.","schema":{"type":"string"}},{"name":"key_prefix","in":"query","required":false,"description":"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.","schema":{"type":"string"}}],"responses":{"200":{"description":"Total spend for the key over the requested window.","content":{"application/json":{"schema":{"type":"object","properties":{"api_key_prefix":{"type":"string","nullable":true,"description":"The requested key prefix, or null when it was omitted and the answer is your own key's spend."},"start":{"type":"string","description":"Window start, resolved to UTC."},"end":{"type":"string","description":"Window end, resolved to UTC."},"spend":{"type":"number","description":"Total spend for the key over the window, in USD."},"currency":{"type":"string","description":"Spend currency (always USD)."},"requests":{"type":"integer","description":"Number of charged requests in the window."}},"required":["api_key_prefix","start","end","spend","currency","requests"]}}}}}}}}}
```

## Get detailed key usage

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

## GET /v2/usage/detail

>

```json
{"openapi":"3.0.0","info":{"title":"AIML API","version":"1.0.0"},"servers":[{"url":"https://api.aimlapi.com"}],"paths":{"/v2/usage/detail":{"get":{"operationId":"_v2_usage_detail","parameters":[{"name":"period","in":"query","required":false,"description":"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.","schema":{"type":"string"}},{"name":"start","in":"query","required":false,"description":"Window start, ISO-8601. A value without a UTC offset is read as UTC. Must be used together with `end`.","schema":{"type":"string"}},{"name":"end","in":"query","required":false,"description":"Window end, ISO-8601. Must not be earlier than `start`, and the window must not exceed 92 days.","schema":{"type":"string"}},{"name":"key_prefix","in":"query","required":false,"description":"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.","schema":{"type":"string"}},{"name":"group_by","in":"query","required":false,"description":"Add a `groups` array to the response, grouped by `day`, by `model`, or by both (`day,model`). Omit it and the response keeps its original shape. Accepted on `/v2/usage/detail` only: `/v2/usage` returns a flat total with nowhere to put a breakdown and answers 400.","schema":{"type":"string","enum":["day","model","day,model"]}},{"name":"tz","in":"query","required":false,"description":"Time zone that defines the day boundary for `group_by=day`. Must be a canonical IANA zone name matched exactly, for example `Europe/Berlin` or `UTC`. Offset forms (`+05:00`) and other-case spellings (`utc`) are rejected with 400. Defaults to UTC. The top-level `start` and `end` stay UTC regardless.","schema":{"type":"string"}}],"responses":{"200":{"description":"Total spend for the key over the requested window, with a per-model breakdown.","content":{"application/json":{"schema":{"type":"object","properties":{"api_key_prefix":{"type":"string","nullable":true,"description":"The requested key prefix, or null when it was omitted and the answer is your own key's spend."},"start":{"type":"string","description":"Window start, resolved to UTC."},"end":{"type":"string","description":"Window end, resolved to UTC."},"spend":{"type":"number","description":"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."},"currency":{"type":"string","description":"Spend currency (always USD)."},"requests":{"type":"integer","description":"Number of charged requests in the window."},"models":{"type":"array","description":"Per-model breakdown, highest spend first.","items":{"type":"object","properties":{"model":{"type":"string","description":"Model name."},"spend":{"type":"number","description":"Spend for this model, in USD."},"requests":{"type":"integer","description":"Charged requests for this model."}},"required":["model","spend","requests"]}},"groups":{"type":"array","description":"Present only when `group_by` is supplied. One entry per group, carrying spend, tokens and request counts. Reconcile the top-level `requests` against `requests.charged`, never against `requests.total`.","items":{"type":"object","properties":{"day":{"type":"string","description":"Present when grouping by day. The day boundary follows `tz`, defaulting to UTC."},"model":{"type":"string","description":"Present when grouping by model."},"spend":{"type":"number","description":"Spend for this group, in USD."},"tokens":{"type":"object","description":"Token counts for this group.","properties":{"input":{"type":"integer"},"output":{"type":"integer"},"total":{"type":"integer"}},"required":["input","output","total"]},"requests":{"type":"object","description":"Request counts for this group. `total` counts every inference; `charged` counts only the billed ones. Failed inferences are billed nothing, so they appear in `total` and `failed` but not in `charged`.","properties":{"total":{"type":"integer"},"charged":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"}},"required":["total","charged","succeeded","failed"]}},"required":["spend","tokens","requests"]}}},"required":["api_key_prefix","start","end","spend","currency","requests","models"]}}}}}}}}}
```

{% hint style="info" %}
Need the individual requests rather than totals — what failed, what a specific call cost, which of your own customers it belonged to? See [Usage Logs](/api-references/service-endpoints/usage-logs.md).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.aimlapi.com/api-references/service-endpoints/api-key-usage.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.