> 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/usage-logs.md).
# Usage Logs
`GET /v2/logs` returns **one row per request** — what it cost, how many tokens it used, whether it succeeded, and the [ids you need to tie it back to your own systems](/capabilities/request-tracing-and-cost.md).\
The time window and key-selection rules are identical to [API Key Usage](/api-references/service-endpoints/api-key-usage.md); use that endpoint when you want totals rather than individual requests.
{% hint style="warning" %}
The `model` and `status` filters do **not** split on commas — repeat the parameter instead (`?status=succeeded&status=failed`). `?model=a,b` is read as one model literally named `a,b`, so it matches nothing and you get an empty page rather than an error.
{% endhint %}
{% hint style="info" %}
Unlike `/v2/usage`, this endpoint lists **failed requests too**, with a zero `cost`. A failed request is billed nothing — the hold is rolled back — so it never appears in the usage totals. That is why a row count here can exceed the `requests` figure `/v2/usage` reports for the same window.
{% endhint %}
### Get request logs
Returns the requests made in the window, with cost, tokens and correlation ids.
## GET /v2/logs
>
```json
{"openapi":"3.0.0","info":{"title":"AIML API","version":"1.0.0"},"servers":[{"url":"https://api.aimlapi.com"}],"paths":{"/v2/logs":{"get":{"operationId":"_v2_logs","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 list the requests made with the key you are authenticating with. Listing the requests of a different key requires a management key.","schema":{"type":"string"}},{"name":"model","in":"query","required":false,"description":"Keep only requests made to this model. Accepts `source/alias` (`openai/gpt-5`) or a bare alias (`gpt-5`), matched exactly. Repeat the parameter once per model to pass several, up to 50 values; a comma-separated list is read as one long name and matches nothing.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Keep only requests with this outcome. Repeat the parameter to accept both (`?status=succeeded&status=failed`); a comma-separated value is not a valid status and returns 400.","schema":{"type":"string","enum":["succeeded","failed"]}},{"name":"limit","in":"query","required":false,"description":"Rows per page, 1-100.","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"description":"Rows to skip before the page starts.","schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"One row per request made in the window, newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","description":"The requested page of request rows.","items":{"type":"object","properties":{"created":{"type":"string","description":"When the request was made, in UTC."},"status":{"type":"string","enum":["succeeded","failed"],"description":"Outcome of the request. A failed request is billed nothing, so its cost is zero."},"origin":{"type":"string","enum":["api","playground"],"description":"Where the request came from."},"model":{"type":"string","description":"Model the request was made to, as `source/alias`."},"cost":{"type":"object","description":"What the request was charged.","properties":{"usd":{"type":"number"},"credits":{"type":"integer"}},"required":["usd","credits"]},"tokens":{"type":"object","description":"Token counts for the request. Zero for models that are not billed per token.","properties":{"input":{"type":"integer"},"output":{"type":"integer"},"total":{"type":"integer"}},"required":["input","output","total"]},"request_id":{"type":"string","nullable":true,"description":"Identifier of the individual HTTP call."},"inference_id":{"type":"string","description":"Identifier of the inference. This is the value returned in the `x-inference-id` response header, and the `reference_id` of the matching charge in `GET /v2/billing/transactions`."},"client_request_id":{"type":"string","nullable":true,"description":"The `X-Client-Request-Id` you sent with the request. Null when you sent none, and on rows recorded before this field existed."}},"required":["created","status","origin","model","cost","tokens","request_id","inference_id","client_request_id"]}},"pagination":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer","description":"Total rows matching the query across all pages."},"has_more":{"type":"boolean","description":"Whether another page follows this one."}},"required":["limit","offset","total","has_more"]}},"required":["data","pagination"]}}}}}}}}}
```
***
### Errors
| Code | When |
| ----- | ------------------------------------------------------------------------------------------------------------------------ |
| `400` | Neither `period` nor `start`+`end`, or both; a malformed date or period; `end` earlier than `start`; window over 92 days |
| `401` | Missing or invalid key |
| `403` | A regular key naming another key's prefix |
| `404` | The prefix is not yours, or is outside your key's scopes |
| `429` | Over 200 requests per 60 seconds |
{% hint style="info" %}
These figures come from the analytics pipeline and are meant for **attribution and budgeting**. For the account ledger — what actually moved your balance, including top-ups — use [`GET /v2/billing/transactions`](/api-references/service-endpoints/account-balance.md#get-account-transactions).
{% 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/usage-logs.md?ask=&goal=
```
`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.