> ## 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 summaries

> Reconciliation checksum fast path: per-key spend rollups grouped by virtual key or end user, 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. 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.



## OpenAPI

````yaml GET /api/gateway/v1/spend-summaries
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-summaries:
    get:
      tags:
        - Gateway Spend
      summary: List spend summaries
      description: >-
        Reconciliation checksum fast path: per-key spend rollups grouped by
        virtual key or end user, 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. 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.
      operationId: getApiGatewayV1Spend-summaries
      parameters:
        - in: query
          name: group_by
          schema:
            type: string
            enum:
              - virtual_key
              - end_user
          required: true
        - in: query
          name: from
          schema:
            type: integer
            exclusiveMinimum: 0
          required: true
        - in: query
          name: to
          schema:
            type: integer
            exclusiveMinimum: 0
          required: true
        - in: query
          name: project_id
          schema:
            type: string
            minLength: 1
            maxLength: 100
          required: false
        - in: query
          name: cursor
          schema:
            type: string
            maxLength: 500
          required: false
        - in: query
          name: limit
          schema:
            type: integer
            exclusiveMinimum: 0
            maximum: 1000
            default: 500
          required: false
        - in: query
          name: virtual_key_id
          schema:
            type: string
            minLength: 1
            maxLength: 100
          required: false
      responses:
        '200':
          description: Per-key spend rollups
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                        event_count:
                          type: integer
                        settled_count:
                          type: integer
                        usage:
                          type: object
                          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
                          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
                      required:
                        - key
                        - event_count
                        - settled_count
                        - usage
                        - cost
                  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
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.

````