> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surnex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get v1usage



## OpenAPI

````yaml https://api.surnex.io/.well-known/openapi.json get /v1/usage
openapi: 3.1.0
info:
  title: Surnex API
  version: 0.2.0
servers:
  - url: https://api.surnex.io
security: []
paths:
  /v1/usage:
    get:
      tags:
        - v1
      parameters:
        - schema:
            type: string
            format: uuid
          required: false
          name: project_id
          in: query
        - schema:
            type: string
            minLength: 1
          required: false
          name: provider
          in: query
        - schema:
            type: string
            minLength: 1
          required: false
          name: from
          in: query
        - schema:
            type: string
            minLength: 1
          required: false
          name: to
          in: query
      responses:
        '200':
          description: Usage + cost rollups
          content:
            application/json:
              schema:
                type: object
                properties:
                  account_id:
                    type: string
                    format: uuid
                  range:
                    type: object
                    properties:
                      from:
                        type:
                          - string
                          - 'null'
                      to:
                        type:
                          - string
                          - 'null'
                    required:
                      - from
                      - to
                  provider:
                    type: string
                  totals:
                    type: object
                    properties:
                      calls_total:
                        type: integer
                        minimum: 0
                      calls_by_operation:
                        type: object
                        additionalProperties:
                          type: integer
                          minimum: 0
                      avg_latency_ms:
                        type:
                          - number
                          - 'null'
                        minimum: 0
                      p95_latency_ms:
                        type:
                          - number
                          - 'null'
                        minimum: 0
                      http_status_counts:
                        type: object
                        properties:
                          2xx:
                            type: integer
                            minimum: 0
                          4xx:
                            type: integer
                            minimum: 0
                          5xx:
                            type: integer
                            minimum: 0
                        required:
                          - 2xx
                          - 4xx
                          - 5xx
                      estimated_cost_usd:
                        type: number
                        minimum: 0
                    required:
                      - calls_total
                      - calls_by_operation
                      - avg_latency_ms
                      - p95_latency_ms
                      - http_status_counts
                      - estimated_cost_usd
                  providers:
                    type: object
                    additionalProperties:
                      type: object
                      properties:
                        calls_total:
                          type: integer
                          minimum: 0
                        calls_by_operation:
                          type: object
                          additionalProperties:
                            type: integer
                            minimum: 0
                        avg_latency_ms:
                          type:
                            - number
                            - 'null'
                          minimum: 0
                        p95_latency_ms:
                          type:
                            - number
                            - 'null'
                          minimum: 0
                        http_status_counts:
                          type: object
                          properties:
                            2xx:
                              type: integer
                              minimum: 0
                            4xx:
                              type: integer
                              minimum: 0
                            5xx:
                              type: integer
                              minimum: 0
                          required:
                            - 2xx
                            - 4xx
                            - 5xx
                        estimated_cost_usd:
                          type: number
                          minimum: 0
                      required:
                        - calls_total
                        - calls_by_operation
                        - avg_latency_ms
                        - p95_latency_ms
                        - http_status_counts
                        - estimated_cost_usd
                  snapshots:
                    type: object
                    properties:
                      snapshots_total:
                        type: integer
                        minimum: 0
                      snapshots_by_status:
                        type: object
                        properties:
                          queued:
                            type: integer
                            minimum: 0
                          running:
                            type: integer
                            minimum: 0
                          complete:
                            type: integer
                            minimum: 0
                          partial:
                            type: integer
                            minimum: 0
                          failed:
                            type: integer
                            minimum: 0
                        required:
                          - queued
                          - running
                          - complete
                          - partial
                          - failed
                    required:
                      - snapshots_total
                      - snapshots_by_status
                required:
                  - account_id
                  - range
                  - provider
                  - totals
                  - providers
                  - snapshots
                description: UsageRollupsResponse
              examples:
                complete:
                  value:
                    account_id: 0f1ce1f3-d6fc-4f1e-9d31-2ed5b1f6ef34
                    range:
                      from: '2026-01-01T00:00:00Z'
                      to: '2026-02-01T00:00:00Z'
                    provider: dataforseo
                    totals:
                      calls_total: 12
                      calls_by_operation:
                        llm_mentions_aggregated_metrics_live: 5
                        llm_mentions_top_domains_live: 4
                        llm_mentions_search_live: 3
                      avg_latency_ms: 190.5
                      p95_latency_ms: 320
                      http_status_counts:
                        2xx: 11
                        4xx: 1
                        5xx: 0
                      estimated_cost_usd: 0.19
                    providers:
                      dataforseo:
                        calls_total: 12
                        calls_by_operation:
                          llm_mentions_aggregated_metrics_live: 5
                          llm_mentions_top_domains_live: 4
                          llm_mentions_search_live: 3
                        avg_latency_ms: 190.5
                        p95_latency_ms: 320
                        http_status_counts:
                          2xx: 11
                          4xx: 1
                          5xx: 0
                        estimated_cost_usd: 0.19
                    snapshots:
                      snapshots_total: 4
                      snapshots_by_status:
                        queued: 0
                        running: 0
                        complete: 3
                        partial: 1
                        failed: 0
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      request_id:
                        type: string
                      details:
                        type: object
                        properties: {}
                        default: {}
                        additionalProperties: {}
                    required:
                      - code
                      - message
                      - request_id
                required:
                  - error
                description: ErrorResponse
              examples:
                invalidDateRange:
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: Invalid request
                      request_id: req_123
                      details:
                        issues:
                          - path:
                              - from
                            message: from must be before to
                            code: custom
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      request_id:
                        type: string
                      details:
                        type: object
                        properties: {}
                        default: {}
                        additionalProperties: {}
                    required:
                      - code
                      - message
                      - request_id
                required:
                  - error
                description: ErrorResponse
              examples:
                unauthorized:
                  value:
                    error:
                      code: UNAUTHORIZED
                      message: Unauthorized
                      request_id: req_123
                      details:
                        reason: missing_or_invalid_api_key
      security:
        - bearerAuth: []
        - apiKeyAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'Authorization: Bearer sk_...'
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````