> ## Documentation Index > Fetch the complete documentation index at: https://docs.hopscotchlabs.ai/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve one request's usage > Read back what one request recorded and what it cost. Send the value of the `x-hopscotch-request-id` header from the response you are asking about. The key that made the request can read it, with no dashboard session. The record is written after the response is sent, so a read taken the instant a response lands can arrive first and answer 404. Read it again a moment later. A record made by another key, a record outside this key's workspace, and an id that never existed all answer with the same 404, so this route cannot be used to learn whether an id exists. In `usage`, null means the provider did not report that count and 0 means it was measured as none. The two are different facts. `charge` is present only when your workspace balance paid for the request. `served_on_own_key` is true when the request ran on your own provider key, and `paid_from_allowance` is true when an included allowance paid for it, in which case `charge` is absent. No prompt and no response body is stored, so none is returned. This route counts against the calling key's own request rate limit, like every other route. ## OpenAPI ````yaml /api-reference/openapi.public.json get /v1/usage/{id} openapi: 3.0.3 info: title: Hopscotch version: v1 description: >- An OpenAI-compatible inference API. Point an OpenAI client at https://api.hopscotchlabs.ai, give it a Hopscotch API key, and call models across providers on one prepaid balance. Every response, errors included, matches the shape an unmodified OpenAI SDK expects. servers: - url: https://api.hopscotchlabs.ai description: Production security: - customerApiKey: [] tags: - name: Chat description: Chat completions, streamed or not. - name: Models description: What you can call. - name: Completions description: Text completions, streamed or not. - name: Messages description: The Anthropic Messages API, streamed or not. - name: Usage description: What one request recorded and what it cost. paths: /v1/usage/{id}: get: tags: - Usage summary: Retrieve one request's usage description: >- Read back what one request recorded and what it cost. Send the value of the `x-hopscotch-request-id` header from the response you are asking about. The key that made the request can read it, with no dashboard session. The record is written after the response is sent, so a read taken the instant a response lands can arrive first and answer 404. Read it again a moment later. A record made by another key, a record outside this key's workspace, and an id that never existed all answer with the same 404, so this route cannot be used to learn whether an id exists. In `usage`, null means the provider did not report that count and 0 means it was measured as none. The two are different facts. `charge` is present only when your workspace balance paid for the request. `served_on_own_key` is true when the request ran on your own provider key, and `paid_from_allowance` is true when an included allowance paid for it, in which case `charge` is absent. No prompt and no response body is stored, so none is returned. This route counts against the calling key's own request rate limit, like every other route. operationId: retrieveRequestUsage parameters: - name: id in: path required: true description: >- The request id: the value the `x-hopscotch-request-id` header carried on the response being asked about. schema: type: string example: REQUEST_ID responses: '200': description: >- The recorded request: when it started, the model that served it, how it ended, every token count a charge can turn on, and the charge with its currency and rate revision. content: application/json: schema: $ref: '#/components/schemas/UsageRecord' example: object: usage.request request_id: REQUEST_ID occurred_at: '2026-09-05T06:20:11.000Z' model: openai/gpt-4o-mini outcome: served streamed: false usage: prompt_tokens: 2011 completion_tokens: 5 total_tokens: 2016 cache_read_tokens: 1800 cache_write_tokens: 0 reasoning_tokens: 0 cache_write_1h_tokens: null charge: amount_micros: 31200 amount: $0.0312 currency: USD rate_revision_id: RATE_REVISION_ID note: null served_on_own_key: false latency_ms: 812 note: >- No prompt and no response body was stored for this request; the figures here are everything that exists (we never store prompts). paid_from_allowance: false headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' '400': description: No request id was named at all, so there is nothing to look up. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: message: >- Name the request id: GET /v1/usage/{request_id}, where the id is the value the x-hopscotch-request-id header carried on the response you are asking about. type: invalid_request_error param: request_id code: missing_required_parameter request_id: REQUEST_ID headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' '401': description: >- No key, a scheme other than Bearer, a key of the wrong shape, a key we reject, or a key past its own expiry date, which carries code `key_expired` and names the date it expired on. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: message: Incorrect API key provided. type: authentication_error param: null code: invalid_api_key request_id: REQUEST_ID headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' '403': description: >- Refused for a setting the caller owns rather than anything about the model, and `code` names which. A key whose account staff have suspended is refused with code `account_suspended`, before any credit is held or any provider is called; contact support, because retrying will not change the answer. content: application/json: schema: $ref: '#/components/schemas/Error' examples: account_suspended: summary: The key's account is suspended value: error: message: >- This account is suspended, so it cannot send requests. Contact support. Request id REQUEST_ID. type: permission_error param: null code: account_suspended request_id: REQUEST_ID headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' '404': description: >- No usage record with that id is visible to this key, with code `request_not_found`. The same answer covers an id that never existed, an id made by another key or in another workspace, and a record this read arrived ahead of. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: message: >- No usage record for "REQUEST_ID" is visible to this key. A record is written after the response is sent, so a read taken immediately can arrive first; a record made by another key, a record outside this key's workspace and an id that never existed answer identically. type: not_found_error param: request_id code: request_not_found request_id: REQUEST_ID headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' '405': description: >- A method other than GET on this path. A usage record is the record of what happened, so there is nothing to write and nothing to delete. The route boundary answers this before any key is looked at. headers: Allow: schema: type: string enum: - GET description: The methods this path accepts. example: GET x-hopscotch-request-id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: message: >- POST is not supported for /v1/usage/REQUEST_ID in this release. type: invalid_request_error param: null code: method_not_allowed request_id: REQUEST_ID '429': description: >- This key's own request rate was reached, `rate_limit_exceeded`. The response carries `Retry-After`. headers: Retry-After: schema: type: integer minimum: 1 example: 17 description: Seconds to wait. x-hopscotch-request-id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: message: >- Rate limit reached for this key. Try again in 12 seconds. Request id REQUEST_ID. type: rate_limit_error param: null code: rate_limit_exceeded request_id: REQUEST_ID '500': description: A fault on our side. The request id is the one thing worth keeping. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: message: >- The server had an error while processing your request. Sorry about that! Quote the request id if you contact support. type: api_error param: null code: null request_id: REQUEST_ID headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' security: - customerApiKey: [] servers: - url: https://api.hopscotchlabs.ai description: Production components: schemas: UsageRecord: type: object description: One request, as the key that made it can read it back. additionalProperties: false required: - object - request_id - occurred_at - model - outcome - streamed - usage - served_on_own_key - paid_from_allowance - latency_ms - note properties: object: type: string enum: - usage.request request_id: type: string description: >- The id the `x-hopscotch-request-id` header carried on the response this record is about. occurred_at: type: string format: date-time description: When the request started, in RFC 3339. model: type: string description: >- The full `provider/model` id the request was served under, the same string GET /v1/models publishes. example: openai/gpt-4o-mini outcome: type: string description: >- How the request ended, from a closed set of words. A request that was answered is `served`. example: served streamed: type: boolean usage: type: object description: >- Every count a charge can turn on. Null means the provider did not report that count. 0 means it reported none. They are not the same fact. additionalProperties: false required: - prompt_tokens - completion_tokens - total_tokens - cache_read_tokens - cache_write_tokens - cache_write_1h_tokens - reasoning_tokens properties: prompt_tokens: type: integer nullable: true completion_tokens: type: integer nullable: true total_tokens: type: integer nullable: true cache_read_tokens: type: integer nullable: true cache_write_tokens: type: integer nullable: true description: >- The cache write at the default lifetime. It does not include `cache_write_1h_tokens`, so add the two to read the whole write. cache_write_1h_tokens: type: integer nullable: true description: >- The one-hour part of the cache write. Null where the provider stated no split. reasoning_tokens: type: integer nullable: true charge: type: object description: >- What the request cost, with what you need to check it against the rates GET /v1/models publishes. Present only when your workspace balance paid for the request, so it is absent when `paid_from_allowance` is true. additionalProperties: false required: - amount_micros - amount - currency - rate_revision_id - note properties: amount_micros: type: integer nullable: true description: >- The charge in millionths of one dollar, so 1000000 is $1.00. Null where the request was never priced, which is not the same as a charge of zero. amount: type: string nullable: true description: >- The same figure as dollars a person reads, with up to six decimal places and trailing zeros trimmed. Null exactly when `amount_micros` is null. example: $0.000105 currency: type: string description: ISO 4217. example: USD rate_revision_id: type: string nullable: true description: >- An opaque id for the set of rates this charge was computed from. Two requests with the same value were priced by the same rates. Null on a record written before rate revisions existed, or one left unpriced. note: type: string nullable: true enum: - rate_absent_charged_at_anchor - estimated_from_delivered_text - exact_from_provider_frame - null description: >- What was unusual about this charge, or null on an ordinary one. `rate_absent_charged_at_anchor`: part of the request was priced at a rate the model does not list, a cache read or write at the input rate or reasoning at the output rate. `estimated_from_delivered_text`: the stream stopped before the provider reported its counts, so the charge is the prompt we counted plus an output estimated from the text delivered, never above the amount held. `exact_from_provider_frame`: the stream stopped early but the provider counts had already arrived, so the charge is exact. served_on_own_key: type: boolean description: >- True when the request ran on your own provider key, which is why nothing was charged. Read this rather than inferring it from a zero charge. paid_from_allowance: type: boolean description: >- True when an included allowance paid for the request, in which case `charge` is absent. latency_ms: type: integer description: Total time the caller waited, in milliseconds. note: type: string description: A fixed sentence saying no prompt and no response body was stored. Error: type: object description: The error envelope. One top-level `error` key, always, at every status. required: - error additionalProperties: false properties: error: type: object required: - message - type - param - code additionalProperties: false properties: message: type: string description: Prose for a person. It may be reworded, so do not branch on it. type: type: string description: The category an SDK branches on. A closed set. enum: - invalid_request_error - authentication_error - permission_error - not_found_error - rate_limit_error - api_error - insufficient_quota - server_error param: type: string nullable: true description: >- The request field at fault, or null. Present and null rather than absent. code: type: string nullable: true description: The stable machine-readable reason. Branch on this. request_id: type: string description: >- Our id for this request, the same value as the x-hopscotch-request-id header. Quote it when you contact support. headers: RequestId: description: >- Our id for this request. Quote it when you contact support. Present on every response, errors included. schema: type: string securitySchemes: customerApiKey: type: http scheme: bearer description: >- A workspace API key in an `Authorization: Bearer` header. A missing header, a scheme other than Bearer, a key of the wrong shape, and a key we reject are all 401. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.