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

# Report token usage

> Read UTC token-usage buckets, optionally filtered and grouped by project, API key or model. Use next_page unchanged with the same filters. Requires billing:read.



## OpenAPI

````yaml /openapi.json get /v1/organization/usage/completions
openapi: 3.1.0
info:
  title: Limitless API
  version: 0.2.0
  description: >-
    Customer inference, scoped organization administration, policies, and health
    probes for Limitless at https://trylimitless.ai. This deployment uses
    sandbox credits and test payments but sends real inference requests. Model
    features depend on the active backend. The OpenAI SDK base URL is
    https://trylimitless.ai/v1.
servers:
  - url: https://trylimitless.ai
    description: >-
      Limitless sandbox API: test payments and real inference. OpenAI SDK
      clients add /v1 to this origin.
security:
  - customerKey: []
tags:
  - name: Health
  - name: Models
  - name: Inference
  - name: Credits
  - name: Organization
  - name: Projects
  - name: Project keys
  - name: Admin keys
  - name: Spending limits
  - name: Reports
  - name: Policies
paths:
  /v1/organization/usage/completions:
    get:
      tags:
        - Reports
      summary: Report token usage
      description: >-
        Read UTC token-usage buckets, optionally filtered and grouped by
        project, API key or model. Use next_page unchanged with the same
        filters. Requires billing:read.
      operationId: retrieveOrganizationUsageCompletions
      parameters:
        - name: start_time
          in: query
          required: true
          schema:
            type: integer
            minimum: 0
          description: Report start as Unix seconds (inclusive).
        - name: end_time
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                minimum: 0
              - type: 'null'
          description: >-
            Report end as Unix seconds (exclusive); defaults to the current
            time.
        - name: bucket_width
          in: query
          required: false
          schema:
            enum:
              - 1m
              - 1h
              - 1d
            type: string
            default: 1d
          description: Length of each UTC usage bucket.
        - name: project_ids
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
                maxItems: 100
              - type: 'null'
          description: >-
            Filter to project IDs within your organization. Repeat this query
            parameter or use comma-separated IDs.
          style: form
          explode: true
        - name: api_key_ids
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
                maxItems: 100
              - type: 'null'
          description: >-
            Filter to customer key IDs. Repeat this parameter or use
            comma-separated IDs.
          style: form
          explode: true
        - name: models
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
                maxItems: 100
              - type: 'null'
          description: Filter to exact model IDs.
          style: form
          explode: true
        - name: group_by
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
                maxItems: 3
              - type: 'null'
          description: >-
            Bucket dimensions. Usage: project_id, api_key_id, model. Costs:
            project_id, api_key_id, line_item.
          style: form
          explode: true
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 1440
            minimum: 1
            default: 7
          description: Maximum records or time buckets to return.
        - name: page
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                minLength: 1
                maxLength: 500
              - type: 'null'
          description: >-
            Opaque next_page value from the previous report response. Keep the
            original report filters.
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdministrationUsagePage'
          description: Successful response.
          headers:
            X-Request-ID:
              description: Gateway request ID for Activity and support.
              schema:
                type: string
                format: uuid
        '400':
          $ref: '#/components/responses/Api400'
        '401':
          $ref: '#/components/responses/Api401'
        '403':
          $ref: '#/components/responses/Api403'
        '404':
          $ref: '#/components/responses/Api404'
        '409':
          $ref: '#/components/responses/Api409'
        '422':
          $ref: '#/components/responses/Api422'
        '429':
          $ref: '#/components/responses/Api429'
        '500':
          $ref: '#/components/responses/Api500'
        '503':
          $ref: '#/components/responses/Api503'
      security:
        - adminKey: []
components:
  schemas:
    AdministrationUsagePage:
      properties:
        object:
          type: string
          const: page
          default: page
        data:
          items:
            $ref: '#/components/schemas/AdministrationUsageBucket'
          type: array
        has_more:
          type: boolean
        next_page:
          anyOf:
            - type: string
            - type: 'null'
      type: object
      required:
        - data
        - has_more
    AdministrationUsageBucket:
      properties:
        object:
          type: string
          const: bucket
          default: bucket
        start_time:
          type: integer
        end_time:
          type: integer
        results:
          items:
            $ref: '#/components/schemas/AdministrationUsageCompletionsResult'
          type: array
      type: object
      required:
        - start_time
        - end_time
        - results
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      type: object
      required:
        - error
    AdministrationUsageCompletionsResult:
      properties:
        object:
          type: string
          const: organization.usage.completions.result
          default: organization.usage.completions.result
        input_tokens:
          type: integer
        input_cached_tokens:
          type: integer
        input_cache_write_tokens:
          type: integer
        input_uncached_tokens:
          type: integer
        output_tokens:
          type: integer
        input_text_tokens:
          anyOf:
            - type: integer
            - type: 'null'
        output_text_tokens:
          anyOf:
            - type: integer
            - type: 'null'
        input_cached_text_tokens:
          anyOf:
            - type: integer
            - type: 'null'
        input_audio_tokens:
          anyOf:
            - type: integer
            - type: 'null'
        input_cached_audio_tokens:
          anyOf:
            - type: integer
            - type: 'null'
        output_audio_tokens:
          anyOf:
            - type: integer
            - type: 'null'
        input_image_tokens:
          anyOf:
            - type: integer
            - type: 'null'
        input_cached_image_tokens:
          anyOf:
            - type: integer
            - type: 'null'
        output_image_tokens:
          anyOf:
            - type: integer
            - type: 'null'
        num_model_requests:
          type: integer
        project_id:
          anyOf:
            - type: string
            - type: 'null'
        user_id:
          type: 'null'
        api_key_id:
          anyOf:
            - type: string
            - type: 'null'
        model:
          anyOf:
            - type: string
            - type: 'null'
        batch:
          type: 'null'
        service_tier:
          type: 'null'
      type: object
      required:
        - input_tokens
        - input_cached_tokens
        - input_cache_write_tokens
        - input_uncached_tokens
        - output_tokens
        - num_model_requests
    ErrorDetail:
      properties:
        code:
          type: string
        message:
          type: string
        type:
          type: string
          description: Error category; policy failures use policy_error.
        param:
          anyOf:
            - type: string
            - type: 'null'
        request_id:
          type: string
        doc_url:
          anyOf:
            - type: string
            - type: 'null'
      type: object
      required:
        - code
        - message
        - type
  responses:
    Api400:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Request validation failed.
      headers:
        X-Request-ID:
          description: Gateway request ID for Activity and support.
          schema:
            type: string
            format: uuid
    Api401:
      headers:
        X-Request-ID:
          description: Gateway request ID for Activity and support.
          schema:
            type: string
            format: uuid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Missing or invalid credential.
    Api403:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Credential scope or policy denied this operation.
      headers:
        X-Request-ID:
          description: Gateway request ID for Activity and support.
          schema:
            type: string
            format: uuid
    Api404:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Resource or model not found in the caller’s organization.
      headers:
        X-Request-ID:
          description: Gateway request ID for Activity and support.
          schema:
            type: string
            format: uuid
    Api409:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Revision, state or idempotency conflict.
      headers:
        X-Request-ID:
          description: Gateway request ID for Activity and support.
          schema:
            type: string
            format: uuid
    Api422:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Provider request validation failed.
      headers:
        X-Request-ID:
          description: Gateway request ID for Activity and support.
          schema:
            type: string
            format: uuid
    Api429:
      headers:
        X-Request-ID:
          description: Gateway request ID for Activity and support.
          schema:
            type: string
            format: uuid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Request rate or concurrency exceeded.
    Api500:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Unexpected gateway failure.
      headers:
        X-Request-ID:
          description: Gateway request ID for Activity and support.
          schema:
            type: string
            format: uuid
    Api503:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: A required service or configuration is unavailable.
      headers:
        X-Request-ID:
          description: Gateway request ID for Activity and support.
          schema:
            type: string
            format: uuid
  securitySchemes:
    customerKey:
      type: http
      scheme: bearer
      bearerFormat: lk_...
      description: >-
        Project customer key. Requires the permission for the requested
        endpoint.
    adminKey:
      type: http
      scheme: bearer
      bearerFormat: lka_...
      description: >-
        Organization Admin API key with an appropriate scope. Customer keys
        cannot call organization routes.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.