> ## 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 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 description: LangWatch openapi spec version: 1.0.0 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: getApiGatewayV1SpendEvents parameters: - 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: 50 type: integer exclusiveMinimum: 0 maximum: 200 - 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 - admitted - confirmed - failed - settled responses: '200': description: Success 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: anyOf: - 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, disjoint from input_tokens. output_image_tokens: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Image tokens the answer was billed for, disjoint from output_tokens. image_count: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Images the request carried. Display only: never part of 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 - type: 'null' cost: anyOf: - type: object properties: total_usd: type: string description: >- Display value. Use nano_usd for arithmetic. nano_usd: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Canonical integer cost, nano-USD. rate_version: type: - string - 'null' required: - total_usd - nano_usd additionalProperties: false - type: 'null' status: type: string needs_reconciliation: type: - boolean - 'null' settle_reason: type: - string - 'null' error: anyOf: - type: object properties: class: type: string http_status: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' required: - class - http_status additionalProperties: false - type: 'null' duration_ms: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' labels: type: array items: type: string metadata: type: object propertyNames: type: string additionalProperties: {} required: - event_id - event_type - gateway_request_id - occurred_at - usage - cost - status - needs_reconciliation - settle_reason - error - duration_ms - labels - metadata additionalProperties: {} required: - id - type - created - schema_version - data 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.