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
- 200
- 400
- 401
- 403
- 404
- 429
- 503
A page of the key's usage records.
A query parameter other than cursor and limit, one of them given twice, a limit outside 1 to 1000, or a cursor that is not a next_cursor of a page read with this key (invalid_request_error, with param).
Missing, malformed or revoked API key (invalid_api_key).
The key's account does not have Sandboxes, so the key has no usage records to read (permission_denied).
A method other than GET (not_found).
Over the key's usage limits, or too many pages being read at once (rate_limit_exceeded). Wait for Retry-After.
Response Headers
Seconds to wait before retrying.
The usage records cannot be read for a moment (upstream_unavailable). Retry after Retry-After.
Response Headers
Seconds to wait before retrying.