> ## 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. # List spend events > Cursor-paged pull over the per-request spend record, ascending by insert order so rows folded late are never skipped by an in-flight cursor. Events are the same canonical objects webhook deliveries carry. Retention is a fixed 13 months, which bounds reconciliation and replay. When feeding a downstream biller, mind its dedup window (Metronome 34 days and Stripe meters 24h+ at the time of writing; both vendors own those numbers, so confirm the current one before you rely on it): re-pulling older ranges into a biller past its window can double-bill. Every filter here is accepted by /spend-summaries too, so a checksum that disagrees can be diffed on exactly the same narrowing; the one difference is `status=admitted`, which only this read answers, because an admitted request is still in flight and contributes no cost to a rollup. Repeat a filter to widen it (`model=a&model=b` matches either); name two different filters to narrow. `metadata` is written `key:value`, split on the first colon, and repeating a key widens that key. `team_id` and `external_id` name Postgres records and are resolved to the projects and keys they cover, so a team with no projects or an external id nobody minted answers with no spend rather than with everything. ## OpenAPI ````yaml GET /api/gateway/v1/spend-events openapi: 3.1.0 info: title: LangWatch API version: 1.0.0 description: LangWatch openapi spec servers: - url: https://app.langwatch.ai security: - project_api_key: [] paths: /api/gateway/v1/spend-events: get: tags: - Gateway Spend summary: List spend events description: >- Cursor-paged pull over the per-request spend record, ascending by insert order so rows folded late are never skipped by an in-flight cursor. Events are the same canonical objects webhook deliveries carry. Retention is a fixed 13 months, which bounds reconciliation and replay. When feeding a downstream biller, mind its dedup window (Metronome 34 days and Stripe meters 24h+ at the time of writing; both vendors own those numbers, so confirm the current one before you rely on it): re-pulling older ranges into a biller past its window can double-bill. Every filter here is accepted by /spend-summaries too, so a checksum that disagrees can be diffed on exactly the same narrowing; the one difference is `status=admitted`, which only this read answers, because an admitted request is still in flight and contributes no cost to a rollup. Repeat a filter to widen it (`model=a&model=b` matches either); name two different filters to narrow. `metadata` is written `key:value`, split on the first colon, and repeating a key widens that key. `team_id` and `external_id` name Postgres records and are resolved to the projects and keys they cover, so a team with no projects or an external id nobody minted answers with no spend rather than with everything. operationId: getApiGatewayV1Spend-events parameters: - in: query name: from schema: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 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. example: 1782864000000 required: true - in: query name: to schema: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 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. example: 1782864000000 required: true - in: query name: cursor schema: type: string maxLength: 500 required: false - in: query name: limit schema: type: integer exclusiveMinimum: 0 maximum: 200 default: 50 required: false - in: query name: project_id schema: anyOf: - type: string minLength: 1 maxLength: 100 - type: array items: type: string minLength: 1 maxLength: 100 maxItems: 100 required: false - in: query name: team_id schema: anyOf: - type: string minLength: 1 maxLength: 100 - type: array items: type: string minLength: 1 maxLength: 100 maxItems: 100 required: false - in: query name: external_id schema: anyOf: - type: string minLength: 1 maxLength: 200 - type: array items: type: string minLength: 1 maxLength: 200 maxItems: 100 required: false - in: query name: virtual_key_id schema: anyOf: - type: string minLength: 1 maxLength: 100 - type: array items: type: string minLength: 1 maxLength: 100 maxItems: 100 required: false - in: query name: end_user_id schema: anyOf: - type: string minLength: 1 maxLength: 256 - type: array items: type: string minLength: 1 maxLength: 256 maxItems: 100 required: false - in: query name: principal_user_id schema: anyOf: - type: string minLength: 1 maxLength: 100 - type: array items: type: string minLength: 1 maxLength: 100 maxItems: 100 required: false - in: query name: model schema: anyOf: - type: string minLength: 1 maxLength: 200 - type: array items: type: string minLength: 1 maxLength: 200 maxItems: 100 required: false - in: query name: provider_key schema: anyOf: - type: string minLength: 1 maxLength: 100 - type: array items: type: string minLength: 1 maxLength: 100 maxItems: 100 required: false - in: query name: request_type schema: anyOf: - type: string minLength: 1 maxLength: 50 - type: array items: type: string minLength: 1 maxLength: 50 maxItems: 100 required: false - in: query name: label schema: anyOf: - type: string minLength: 1 maxLength: 200 - type: array items: type: string minLength: 1 maxLength: 200 maxItems: 100 required: false - in: query name: metadata schema: anyOf: - type: string minLength: 3 maxLength: 640 - type: array items: type: string minLength: 3 maxLength: 640 maxItems: 100 required: false - in: query name: status schema: type: string enum: - success - error - admitted - confirmed - failed - settled required: false responses: '200': description: One page of billing envelopes content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string type: type: string created: type: string schema_version: type: string data: type: object properties: event_id: type: string event_type: type: string gateway_request_id: type: string occurred_at: type: string usage: type: - object - 'null' properties: input_tokens: type: integer output_tokens: type: integer cache_read_input_tokens: type: integer cache_creation_input_tokens: type: integer reasoning_tokens: type: integer required: - input_tokens - output_tokens - cache_read_input_tokens - cache_creation_input_tokens - reasoning_tokens cost: type: - object - 'null' 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 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 status: type: string needs_reconciliation: type: - boolean - 'null' settle_reason: type: - string - 'null' error: type: - object - 'null' properties: class: type: string http_status: type: - integer - 'null' required: - class - http_status duration_ms: type: - integer - 'null' labels: type: array items: type: string metadata: type: object additionalProperties: {} required: - event_id - event_type - gateway_request_id - occurred_at - usage - cost - status - needs_reconciliation - settle_reason - error - duration_ms - labels - metadata additionalProperties: true required: - id - type - created - schema_version - data next_cursor: type: - string - 'null' required: - data - next_cursor '400': description: Bad Request content: application/json: schema: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string meta: type: object additionalProperties: {} trace_id: type: string span_id: type: string required: - type - code - message required: - error '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string meta: type: object additionalProperties: {} trace_id: type: string span_id: type: string required: - type - code - message required: - error '403': description: Forbidden content: application/json: schema: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string meta: type: object additionalProperties: {} trace_id: type: string span_id: type: string required: - type - code - message required: - error '500': description: Internal Server Error content: application/json: schema: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string meta: type: object additionalProperties: {} trace_id: type: string span_id: type: string required: - type - code - message required: - error 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}. ````