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

# Get usage by time bucket, model and key



## OpenAPI

````yaml https://api.blon.ai/v1/openapi.json get /usage
openapi: 3.1.0
info:
  title: Blon API
  version: v1
servers:
  - url: https://api.blon.ai/v1
security: []
paths:
  /usage:
    get:
      summary: Get usage by time bucket, model and key
      operationId: getUsage
      parameters:
        - name: workspace_id
          in: query
          required: false
          schema:
            type: string
            minLength: 1
        - name: timeframe
          in: query
          required: false
          schema:
            type: string
            enum:
              - hour
              - day
              - week
              - month
        - name: start
          in: query
          required: false
          schema:
            description: RFC 3339; default end − 7 days.
            type: string
            format: date-time
            pattern: >-
              ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
        - name: end
          in: query
          required: false
          schema:
            description: RFC 3339; default now. At most 31 days after start.
            type: string
            format: date-time
            pattern: >-
              ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
      responses:
        '200':
          description: Settled jobs only; not an invoice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
        '400':
          description: '`bad_request`, `invalid_input`, `unknown_parameter`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: '`unauthorized`, `session_not_accepted`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '402':
          description: '`insufficient_credits`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: >-
            `forbidden`, `spending_disabled`, `monthly_cap_exceeded`,
            `api_key_spend_limit_exceeded`, `insufficient_scope`,
            `plan_required`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: '`not_found`, `model_not_found`, `workspace_not_found`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '408':
          description: '`request_timeout` (retryable)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: >-
            `conflict`, `idempotency_conflict`, `model_price_unavailable`,
            `job_not_cancelable`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '412':
          description: '`precondition_failed`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '413':
          description: '`payload_too_large`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '415':
          description: '`unsupported_media_type`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: '`input_media_unreadable`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: >-
            `queue_full` (retryable), `concurrency_limit` (retryable),
            `rate_limited` (retryable)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: '`internal_error` (retryable)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '501':
          description: '`not_implemented`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '502':
          description: '`provider_submission_failed`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: >-
            `provider_capacity_exceeded` (retryable), `provider_unavailable`
            (retryable), `model_disabled` (retryable), `service_unavailable`
            (retryable)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
        - bearer: []
        - apiKey: []
components:
  schemas:
    Usage:
      type: object
      properties:
        currency:
          type: string
          enum:
            - CREDITS
            - USD
        timeframe:
          type: string
          enum:
            - hour
            - day
            - week
            - month
        start:
          type: string
        end:
          type: string
        data:
          type: array
          items:
            type: object
            properties:
              bucket_start:
                type: string
                description: UTC start of the bucket.
              model:
                type: string
              api_key_id:
                type:
                  - string
                  - 'null'
              jobs:
                type: number
              units:
                type: object
                propertyNames:
                  type: string
                  enum:
                    - output_seconds
                    - input_seconds
                    - output_images
                    - input_items
                    - input_chars_per_1000
                    - per_invocation
                    - input_tokens_per_1m
                    - output_tokens_per_1m
                    - sandbox_runtime_seconds
                    - container_seconds
                additionalProperties:
                  type: number
              cost:
                type: string
                description: Charged net of refunds.
            required:
              - bucket_start
              - model
              - api_key_id
              - jobs
              - units
              - cost
      required:
        - currency
        - timeframe
        - start
        - end
        - data
      description: >-
        Settled jobs only, bucketed by settlement time. A usage report, not an
        invoice.
    ApiError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - bad_request
                - invalid_input
                - unknown_parameter
                - unauthorized
                - session_not_accepted
                - insufficient_credits
                - forbidden
                - spending_disabled
                - monthly_cap_exceeded
                - api_key_spend_limit_exceeded
                - insufficient_scope
                - plan_required
                - not_found
                - model_not_found
                - workspace_not_found
                - request_timeout
                - conflict
                - idempotency_conflict
                - model_price_unavailable
                - job_not_cancelable
                - precondition_failed
                - payload_too_large
                - unsupported_media_type
                - input_media_unreadable
                - queue_full
                - concurrency_limit
                - rate_limited
                - internal_error
                - not_implemented
                - provider_submission_failed
                - provider_capacity_exceeded
                - provider_unavailable
                - model_disabled
                - service_unavailable
            message:
              type: string
            request_id:
              type: string
            retryable:
              type: boolean
            retry_after_seconds:
              type:
                - number
                - 'null'
            details: {}
          required:
            - code
            - message
            - request_id
            - retryable
            - retry_after_seconds
            - details
      required:
        - error
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
    apiKey:
      type: apiKey
      in: header
      name: x-api-key

````

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