Read usage

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

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.

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.

{ "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 } ] }

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.

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