# Read usage

GET /v1/usage reports the account's month and each key's share of it.

Page: https://legivel.com/docs/api/usage

GET/v1/usage

`https://api.legivel.com/v1/usage` reports how many of the current period's documents the account has used, and how that total splits across its keys. Pass `period` to read a specific usage period instead.

## Request

There is no body. One optional query parameter and one header:

| Name | Type | Description |
| --- | --- | --- |
| `period` | query · string | A usage period id of this account. Omit it for the period that is open now. A well-formed id that is not this account's answers 404, the same as an unknown one. Matches `^[1-9]\d{0,18}$`. |
| `Authorization`required | header | `Bearer lgv_your_key_here`, an API key from the account page. See [Authentication](https://legivel.com/docs/authentication). |

A period that is not one of this account's answers `404` `not_found`: The usage period asked for does not belong to this account, or the path does not exist.

## Response

200 with `Content-Type: application/json` and `Cache-Control: no-store`.

```json
{ "plan": "free",
  "period_start": "2026-09-09T00:00:00.000Z", "period_end": "2026-10-09T00:00:00.000Z",
  "credits_included": 100, "credits_granted": 0, "credits_used": 3,
  "limits": { "markdown_kb": 512, "resources_mb": 1.5, "pages_max": 20,
              "timeout_s": 30, "concurrency": 1, "requests_per_min": 5, "previews_per_hour": 120 },
  "keys": [ { "id": "<apikey.id>", "name": "CI", "credits": 2 } ] }
```

Sign in and this block shows your own account.

| Name | Type | Description |
| --- | --- | --- |
| `plan`required | string | The id of the plan the period is counted against. |
| `period_start`required | string | When the period opened. Date-time format. |
| `period_end`required | string | When the period closes. Date-time format. |
| `credits_included`required | integer | Documents the plan includes in the period. |
| `credits_granted`required | integer | Documents granted on top of the plan's, such as carry-over on an upgrade. |
| `credits_used`required | integer | Documents used in the period, editor downloads included; this is the number a 402 reads. |
| `limits`required | object | The limits in force for the account in this period, from its plan. |
| `limits.markdown_kb`required | integer | Largest Markdown document, in kibibytes. |
| `limits.resources_mb`required | number | Total resource bytes one render may load, in mebibytes. |
| `limits.pages_max`required | integer | Most pages one rendered document may have. |
| `limits.timeout_s`required | integer | Longest one render may run, in seconds. |
| `limits.concurrency`required | integer | Renders the account may have in flight at once. |
| `limits.requests_per_min`required | integer | Requests a minute before the burst limiter refuses. |
| `limits.previews_per_hour`required | integer | Editor previews an hour; the API never spends these. |
| `keys`required | object[] | The period's spending split by API key. The editor's share is `credits_used` less the sum of these, so the two need not add up. |
| `keys[].id`required | string | The API key's id. |
| `keys[].name`required | string \| null | The key's current name; null once the key is gone. |
| `keys[].credits`required | integer | Documents charged through this key, returned documents excluded. At least 0. |

## Example

Fetch the current period's usage and print it.

```bash
curl https://api.legivel.com/v1/usage \
  -H "Authorization: Bearer $LEGIVEL_API_KEY"
```

## Notes

- Scheduled periods follow the account's anchor day at 00:00 UTC, using the last day of shorter months without moving the anchor. The account page selects actual periods, including separate periods that start within the same calendar month.
- Reading usage does not open a period. Before the first render in a new period, usage is zero, `keys` is empty and the boundaries are those the period will have.
- Grants add documents to the period without changing `credits_included`; they are reported separately as `credits_granted`. An earlier period keeps the documents it included and its grants; `limits` reflects that plan's current values.
- A malformed `period` answers 400 `invalid_request`; an unknown ID or another account's period answers 404 `not_found`.
- The MCP `get_usage` tool returns this same object and takes the same optional `period`. See [MCP server](https://legivel.com/docs/mcp).
- The account page's chart, history and CSV show accepted render attempts, with editor downloads as their own line in the breakdown. Returned documents remain visible in history but do not count toward usage. Requests rejected before a render was accepted do not appear there.