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

# Get usage and limits

> Returns aggregate usage for the current UTC calendar month, the limits assigned to the tenant, and current remaining token and document allowances. Token values are decimal strings to prevent integer precision loss.




## OpenAPI

````yaml /openapi/openapi.yaml get /v1/usage
openapi: 3.1.0
info:
  title: BreadBowl Embed API (Alpha)
  version: 0.1.0-alpha
  description: >
    REST API for managed multi-vector retrieval and transient document scoring.


    BreadBowl Embed accepts source text and returns ranked document and chunk
    references. It does not return conventional embedding vectors.
servers:
  - url: https://embed.breadbowl.ai
    description: Production API
security:
  - bearerAuth: []
tags:
  - name: Service health
    description: Unauthenticated liveness and readiness checks
  - name: Indexes
    description: Create and discover tenant-scoped indexes
  - name: Documents
    description: Upsert and delete indexed documents
  - name: Retrieval
    description: Search an index or score a transient candidate set
  - name: Usage
    description: Inspect current UTC-month usage and assigned limits
paths:
  /v1/usage:
    get:
      tags:
        - Usage
      summary: Get usage and limits
      description: >
        Returns aggregate usage for the current UTC calendar month, the limits
        assigned to the tenant, and current remaining token and document
        allowances. Token values are decimal strings to prevent integer
        precision loss.
      operationId: getUsage
      responses:
        '200':
          description: Current usage summary
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
              example:
                period_start: '2026-07-01T00:00:00.000Z'
                period_end: '2026-08-01T00:00:00.000Z'
                usage:
                  input_tokens: '128450'
                  requests: 842
                  document_upserts: 400
                  searches: 437
                  scores: 5
                  documents: 398
                limits:
                  input_tokens: '50000000'
                  documents: 100000
                  requests_per_minute: 60
                  max_concurrent_requests: 2
                remaining:
                  input_tokens: '49871550'
                  documents: 99602
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  headers:
    RequestId:
      description: Correlation ID for logging and support. This is not a credential.
      schema:
        type: string
        minLength: 1
  schemas:
    UsageResponse:
      type: object
      additionalProperties: false
      required:
        - period_start
        - period_end
        - usage
        - limits
        - remaining
      properties:
        period_start:
          type: string
          format: date-time
          description: Inclusive start of the current UTC calendar month.
        period_end:
          type: string
          format: date-time
          description: Exclusive start of the next UTC calendar month.
        usage:
          type: object
          additionalProperties: false
          required:
            - input_tokens
            - requests
            - document_upserts
            - searches
            - scores
            - documents
          properties:
            input_tokens:
              $ref: '#/components/schemas/DecimalInteger'
            requests:
              type: integer
              minimum: 0
            document_upserts:
              type: integer
              minimum: 0
              description: Number of document-upsert usage events, not number of documents.
            searches:
              type: integer
              minimum: 0
            scores:
              type: integer
              minimum: 0
            documents:
              type: integer
              minimum: 0
              description: Documents currently stored across the tenant.
        limits:
          type: object
          additionalProperties: false
          required:
            - input_tokens
            - documents
            - requests_per_minute
            - max_concurrent_requests
          properties:
            input_tokens:
              $ref: '#/components/schemas/DecimalInteger'
            documents:
              type: integer
              minimum: 0
            requests_per_minute:
              type: integer
              minimum: 1
            max_concurrent_requests:
              type: integer
              minimum: 1
        remaining:
          type: object
          additionalProperties: false
          required:
            - input_tokens
            - documents
          properties:
            input_tokens:
              $ref: '#/components/schemas/DecimalInteger'
            documents:
              type: integer
              minimum: 0
    DecimalInteger:
      type: string
      pattern: ^[0-9]+$
      description: Non-negative base-10 integer encoded as a string.
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - message
          properties:
            code:
              type: string
              examples:
                - validation_error
            message:
              type: string
            issues:
              type: array
              description: Optional field-level validation details.
              items: {}
  responses:
    Unauthorized:
      description: API key is missing, invalid, or revoked
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: authentication_failed
              message: Authentication failed
    Forbidden:
      description: Tenant is suspended
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: tenant_suspended
              message: Tenant is suspended
    RateLimited:
      description: Request, concurrency, or monthly token limit was reached
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
        Retry-After:
          description: Minimum seconds before retrying.
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            rate:
              value:
                error:
                  code: rate_limit_exceeded
                  message: Tenant request rate exceeded
            concurrency:
              value:
                error:
                  code: concurrency_limit_exceeded
                  message: Tenant concurrency limit exceeded
            usage:
              value:
                error:
                  code: usage_limit_exceeded
                  message: Monthly input-token allowance exhausted
    InternalError:
      description: Unexpected service failure
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: internal_error
              message: Internal server error
    ServiceUnavailable:
      description: Service cannot process the request temporarily
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: service_unavailable
              message: Service is temporarily unavailable
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: BreadBowl Embed API key
      description: Tenant-scoped API key beginning with `qkv_live_`.

````