> ## Documentation Index > Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details. # List spend summaries > Reconciliation checksum fast path: spend rollups with token classes and integer nano-USD cost. Settled (unpriced) requests are counted separately as settled_count and never included in cost sums. Diff individual items via /spend-events only when a checksum diverges. `group_by` takes one or two of virtual_key, end_user, project, model, provider, principal and request_type, comma-separated, and `bucket` adds an hour or day column in the `timezone` you name. `key` stays the first dimension's value for consumers written against the single-dimension surface; read `group` to tell two dimensions apart. Paged by group key ascending: follow next_cursor until it comes back null, because a page that is full does not mean the window held nothing more. Grouping by model or provider, or into time buckets, is refused with `gateway_spend_group_by_unstable` while the window is recent enough that outcomes can still arrive, because those groups can move under a page walk and the totals would double-count some requests and miss others; ask for an older range, or send `allow_unstable` when an approximate shape is enough. Every filter here is accepted by /spend-events too, and the reverse holds apart from `status=admitted`: a rollup sums the cost of requests past admission, so an admitted request has none to contribute and that narrowing is refused rather than answered with a zero. Ask /spend-events for those. ## OpenAPI ````yaml GET /api/gateway/v1/spend-summaries openapi: 3.1.0 info: title: LangWatch API description: LangWatch openapi spec version: 1.0.0 servers: - url: https://app.langwatch.ai security: - project_api_key: [] paths: /api/gateway/v1/spend-summaries: get: tags: - Gateway Spend summary: List spend summaries description: >- Reconciliation checksum fast path: spend rollups with token classes and integer nano-USD cost. Settled (unpriced) requests are counted separately as settled_count and never included in cost sums. Diff individual items via /spend-events only when a checksum diverges. `group_by` takes one or two of virtual_key, end_user, project, model, provider, principal and request_type, comma-separated, and `bucket` adds an hour or day column in the `timezone` you name. `key` stays the first dimension's value for consumers written against the single-dimension surface; read `group` to tell two dimensions apart. Paged by group key ascending: follow next_cursor until it comes back null, because a page that is full does not mean the window held nothing more. Grouping by model or provider, or into time buckets, is refused with `gateway_spend_group_by_unstable` while the window is recent enough that outcomes can still arrive, because those groups can move under a page walk and the totals would double-count some requests and miss others; ask for an older range, or send `allow_unstable` when an approximate shape is enough. Every filter here is accepted by /spend-events too, and the reverse holds apart from `status=admitted`: a rollup sums the cost of requests past admission, so an admitted request has none to contribute and that narrowing is refused rather than answered with a zero. Ask /spend-events for those. operationId: getApiGatewayV1SpendSummaries parameters: - in: query name: group_by schema: example: model,end_user type: string required: true description: >- One or two dimensions, comma separated: virtual_key, end_user, project, model, provider, principal, request_type. A dimension may not repeat. Each row's `key` is the first dimension's value and `group` names them all, so two rows may share a key. - in: query name: bucket schema: default: none type: string enum: - none - hour - day - in: query name: timezone schema: default: UTC type: string minLength: 1 maxLength: 64 - in: query name: allow_unstable schema: example: 'true' default: 'false' type: string description: >- true, 1, yes for yes; false, 0, no or omitted for no. Case does not matter, so a Python True is accepted as sent. - in: query name: from schema: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 example: 1782864000000 required: true description: >- Milliseconds since the Unix epoch, not seconds. An epoch in seconds is a valid integer here and answers for 1970, so a mismatched unit reads as an empty window rather than as an error. - in: query name: to schema: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 example: 1782864000000 required: true description: >- Milliseconds since the Unix epoch, not seconds. An epoch in seconds is a valid integer here and answers for 1970, so a mismatched unit reads as an empty window rather than as an error. - in: query name: cursor schema: type: string maxLength: 500 - in: query name: limit schema: default: 500 type: integer exclusiveMinimum: 0 maximum: 1000 - in: query name: project_id schema: anyOf: - type: string minLength: 1 maxLength: 100 - maxItems: 100 type: array items: type: string minLength: 1 maxLength: 100 - in: query name: team_id schema: anyOf: - type: string minLength: 1 maxLength: 100 - maxItems: 100 type: array items: type: string minLength: 1 maxLength: 100 - in: query name: external_id schema: anyOf: - type: string minLength: 1 maxLength: 200 - maxItems: 100 type: array items: type: string minLength: 1 maxLength: 200 - in: query name: virtual_key_id schema: anyOf: - type: string minLength: 1 maxLength: 100 - maxItems: 100 type: array items: type: string minLength: 1 maxLength: 100 - in: query name: end_user_id schema: anyOf: - type: string minLength: 1 maxLength: 256 - maxItems: 100 type: array items: type: string minLength: 1 maxLength: 256 - in: query name: principal_user_id schema: anyOf: - type: string minLength: 1 maxLength: 100 - maxItems: 100 type: array items: type: string minLength: 1 maxLength: 100 - in: query name: model schema: anyOf: - type: string minLength: 1 maxLength: 200 - maxItems: 100 type: array items: type: string minLength: 1 maxLength: 200 - in: query name: provider_key schema: anyOf: - type: string minLength: 1 maxLength: 100 - maxItems: 100 type: array items: type: string minLength: 1 maxLength: 100 - in: query name: request_type schema: anyOf: - type: string minLength: 1 maxLength: 50 - maxItems: 100 type: array items: type: string minLength: 1 maxLength: 50 - in: query name: label schema: anyOf: - type: string minLength: 1 maxLength: 200 - maxItems: 100 type: array items: type: string minLength: 1 maxLength: 200 - in: query name: metadata schema: anyOf: - type: string minLength: 3 maxLength: 640 - maxItems: 100 type: array items: type: string minLength: 3 maxLength: 640 - in: query name: status schema: type: string enum: - success - error - confirmed - failed - settled description: >- Narrow to one lifecycle status. `admitted` is not accepted here: a rollup sums the cost of requests past admission, and an admitted request is still in flight with no cost of its own yet. Ask /spend-events for those. responses: '200': description: Success content: application/json: schema: type: object properties: data: type: array items: type: object properties: key: type: string group: type: object propertyNames: type: string additionalProperties: type: string bucket_start: type: - string - 'null' event_count: type: integer minimum: -9007199254740991 maximum: 9007199254740991 settled_count: type: integer minimum: -9007199254740991 maximum: 9007199254740991 usage: type: object properties: input_tokens: type: integer minimum: -9007199254740991 maximum: 9007199254740991 output_tokens: type: integer minimum: -9007199254740991 maximum: 9007199254740991 cache_read_input_tokens: type: integer minimum: -9007199254740991 maximum: 9007199254740991 cache_creation_input_tokens: type: integer minimum: -9007199254740991 maximum: 9007199254740991 reasoning_tokens: type: integer minimum: -9007199254740991 maximum: 9007199254740991 input_image_tokens: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Image tokens billed on the input side, 0 when no image was used. Priced at its own rate and disjoint from input_tokens, which never includes it. output_image_tokens: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Image tokens the answer was billed for, 0 when no answer held one. Priced at its own rate and disjoint from output_tokens: an image_generation row reports output_tokens 0 and its render here, so a reconciler reading output_tokens alone sees none of the image traffic. image_count: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Images carried, 0 when none were. Display only: no rate prices it, so it never belongs in a cost sum. required: - input_tokens - output_tokens - cache_read_input_tokens - cache_creation_input_tokens - reasoning_tokens - input_image_tokens - output_image_tokens - image_count additionalProperties: false cost: type: object properties: total_usd: type: string description: >- Display value. Decimal string, up to 9 fractional digits, trailing zeros trimmed, never exponent notation. Use nano_usd for arithmetic. nano_usd: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Canonical integer cost, nano-USD. Rated as an integer and summed as one, so this is the figure to reconcile against. required: - total_usd - nano_usd additionalProperties: false required: - key - group - bucket_start - event_count - settled_count - usage - cost additionalProperties: false next_cursor: type: - string - 'null' required: - data - next_cursor additionalProperties: false '400': description: Bad Request content: application/json: schema: type: object properties: type: type: string code: type: string message: type: string retryable: type: boolean meta: type: object propertyNames: type: string additionalProperties: {} trace_id: type: string span_id: type: string trace: type: object properties: traceId: type: string spanId: type: string traceUrl: type: string logsUrl: type: string tips: type: array items: type: string docs_url: type: string fault: type: string enum: - customer - platform - provider - presumed_platform reasons: type: array items: {} required: - type - code - message - retryable '401': description: Unauthorized content: application/json: schema: type: object properties: type: type: string code: type: string message: type: string retryable: type: boolean meta: type: object propertyNames: type: string additionalProperties: {} trace_id: type: string span_id: type: string trace: type: object properties: traceId: type: string spanId: type: string traceUrl: type: string logsUrl: type: string tips: type: array items: type: string docs_url: type: string fault: type: string enum: - customer - platform - provider - presumed_platform reasons: type: array items: {} required: - type - code - message - retryable '403': description: Forbidden content: application/json: schema: type: object properties: type: type: string code: type: string message: type: string retryable: type: boolean meta: type: object propertyNames: type: string additionalProperties: {} trace_id: type: string span_id: type: string trace: type: object properties: traceId: type: string spanId: type: string traceUrl: type: string logsUrl: type: string tips: type: array items: type: string docs_url: type: string fault: type: string enum: - customer - platform - provider - presumed_platform reasons: type: array items: {} required: - type - code - message - retryable '500': description: Internal Server Error content: application/json: schema: type: object properties: type: type: string code: type: string message: type: string retryable: type: boolean meta: type: object propertyNames: type: string additionalProperties: {} trace_id: type: string span_id: type: string trace: type: object properties: traceId: type: string spanId: type: string traceUrl: type: string logsUrl: type: string tips: type: array items: type: string docs_url: type: string fault: type: string enum: - customer - platform - provider - presumed_platform reasons: type: array items: {} required: - type - code - message - retryable security: - admin_api_key: [] components: securitySchemes: project_api_key: type: apiKey in: header name: X-Auth-Token description: >- Project API key for sending traces and accessing project-scoped resources. Format: sk-lw-... (no underscore). Obtain one by creating a project via the Admin API or the LangWatch UI. admin_api_key: type: http scheme: bearer description: >- Admin API key for organization-level operations (managing projects, API keys). Create one in Settings > API Keys or via POST /api/api-keys. Format: sk-lw-{id}_{secret}. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.