Skip to main content

Read usage records

GET 

/usage

Returns the usage records of the API key that makes the call, page by page, in the order they were written. Today the answer has one block, sandboxes: the usage records of the Sandboxes created with this key, the records your sandbox invoice is computed from. Inference has no usage records to read: the usage object of each response is what is billed.

Whose records. The calling key's only. Each key of an account reads the records of the sandboxes it created, and no other key's. Send the key as Authorization: Bearer <key> or as X-API-Key: <key>. A key whose account does not have Sandboxes gets 403 permission_denied; a key of an account with Sandboxes that has not created a sandbox yet gets an empty page.

Paging. Start without cursor, then send the next_cursor of each page as cursor until has_more is false. The cursor is opaque and belongs to the key that read the page. Keep the last next_cursor to read only the records written since.

Freshness. A running sandbox's record is written every 5 minutes and when the run ends, a paused sandbox's every hour and when the pause ends. watermark is the time up to which every sandbox event has been recorded.

Limits. Each key may have 2 usage requests in flight and make 30 per minute. They are apart from the key's control API limits: reading usage never uses the budget of your sandbox calls, nor they its budget. Over them, the answer is 429 rate_limit_exceeded with Retry-After.

Errors are in the OpenAI error format. See Check your usage.

Request​

Responses​

A page of the key's usage records.