> ## Documentation Index > Fetch the complete documentation index at: https://docs.2501.ai/llms.txt > Use this file to discover all available pages before exploring further. # List LLM usage > Newest first: one row per call to a model, with the tokens it used. The `created_gte` / `created_lte` bounds (ISO 8601, inclusive) narrow the list, so a connector can read only what is new. Join `model_id` to `GET /api/v1/llm-models` on `id` (or, where `model_id` is null, `model` on the `key` of a model with no `archived_at`), then to `GET /api/v1/llm-pricing-plans` on the plan covering the row's date, to compute cost: `((input_tokens - cached_tokens) × input_price_per_mtok + cached_tokens × cached_price_per_mtok + output_tokens × output_price_per_mtok) / 1,000,000`. `cached_tokens` is a part of `input_tokens`, billed at the cached price instead of the input price. A removed model is archived, not deleted: it stays in the model list with `archived_at` set, with its pricing plans, so its past usage keeps its price. This list holds every call of the organization, while the Usage page counts only calls tied to a ticket, so a total built from it can be higher than the page's. ## OpenAPI ````yaml /0.20/openapi.json get /api/v1/llm-usage openapi: 3.0.3 info: title: 2501 Public API version: v1 description: >- The stable, versioned HTTP API for driving 2501 as code. See the API Overview for authentication, the org_id rule, cursor pagination, and the error envelope. servers: - url: https://{command_center_host} variables: command_center_host: default: your-command-center-host description: Your Command Center host security: - bearerAuth: [] paths: /api/v1/llm-usage: get: tags: - Usage summary: List LLM usage description: >- Newest first: one row per call to a model, with the tokens it used. The `created_gte` / `created_lte` bounds (ISO 8601, inclusive) narrow the list, so a connector can read only what is new. Join `model_id` to `GET /api/v1/llm-models` on `id` (or, where `model_id` is null, `model` on the `key` of a model with no `archived_at`), then to `GET /api/v1/llm-pricing-plans` on the plan covering the row's date, to compute cost: `((input_tokens - cached_tokens) × input_price_per_mtok + cached_tokens × cached_price_per_mtok + output_tokens × output_price_per_mtok) / 1,000,000`. `cached_tokens` is a part of `input_tokens`, billed at the cached price instead of the input price. A removed model is archived, not deleted: it stays in the model list with `archived_at` set, with its pricing plans, so its past usage keeps its price. This list holds every call of the organization, while the Usage page counts only calls tied to a ticket, so a total built from it can be higher than the page's. parameters: - schema: type: string default: '25' required: false name: limit in: query - schema: type: string required: false name: starting_after in: query - schema: type: string required: false name: ending_before in: query - schema: anyOf: - type: string enum: - total_count - type: array items: type: string enum: - total_count required: false name: include in: query - schema: type: string required: true name: org_id in: query - schema: type: string format: date-time required: false name: created_gte in: query - schema: type: string format: date-time required: false name: created_lte in: query responses: '200': description: A page of the organization's LLM usage content: application/json: schema: $ref: '#/components/schemas/LlmUsageList' '400': description: >- Bad request - a field is missing, malformed, or not allowed (VALIDATION_FAILED, BAD_REQUEST, INVALID_CURSOR) content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: >- No credentials, or a key that is invalid, revoked, or expired (UNAUTHORIZED) content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- Authenticated but not allowed (FORBIDDEN, ORG_ACCESS_DENIED, STEP_UP_REFUSED, TWO_FACTOR_ENROLLMENT_REQUIRED, LICENSE_CAP_REACHED, LICENSE_EXPIRED) content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: LlmUsageList: type: object properties: object: type: string enum: - list data: type: array items: $ref: '#/components/schemas/LlmUsage' has_more: type: boolean total_count: type: integer description: Present only when include=total_count is set required: - object - data - has_more Error: type: object properties: code: type: string example: VALIDATION_FAILED message: type: string example: Validation failed request_id: type: string example: req_3702b7e7-... field: type: string description: Set when one input is at fault errors: type: array items: type: object properties: field: type: string message: type: string required: - field - message description: Set when several inputs are at fault details: type: object additionalProperties: nullable: true required: - code - message - request_id LlmUsage: type: object properties: id: type: string example: llu_8c2f4b6d-... org_id: type: string ticket_id: type: string nullable: true job_id: type: string nullable: true task_id: type: string nullable: true agent_id: type: string nullable: true model: type: string description: The key of the model that answered, as it was at the time model_id: type: string nullable: true description: >- The LlmModel that answered; it survives a rename of the key and the archiving of the model. Null when the recorded key matched no model; such a row falls back to `model` on `key` input_tokens: type: integer description: All input tokens of the call, cached ones included output_tokens: type: integer cached_tokens: type: integer nullable: true description: >- The input tokens read from the provider cache, a part of input_tokens; null when none were reported, which counts as 0 created_at: type: string format: date-time example: '2026-08-26T10:00:26.380Z' required: - id - org_id - ticket_id - job_id - task_id - agent_id - model - model_id - input_tokens - output_tokens - cached_tokens - created_at securitySchemes: bearerAuth: type: http scheme: bearer description: >- An API key minted in Command Center (Settings -> API Keys), sent as `Authorization: Bearer 2501_ak_...`. A Command Center session cookie is also accepted. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.