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

# AI spend ceiling

> Today's AI spend per purpose against the daily ceiling, the contract's or the default, and when waiting work resumes.



## OpenAPI

````yaml openapi/en/cell.json GET /v1/usage/budget
openapi: 3.1.0
info:
  title: Niadra data API
  version: '1'
  description: >-
    Writing, context, history, objects, identity, privacy and governance of one
    space. Every space has a stable address, with the space and the region in
    its name.
servers:
  - url: https://{space}.{region}.api.niadra.com
    variables:
      space:
        default: acme-prod
        description: The space, which comes in the source key.
      region:
        default: us-east-2
        description: The region of the space, which also comes in the key.
security: []
paths:
  /v1/usage/budget:
    get:
      tags:
        - usage
      summary: AI spend ceiling
      description: >-
        Today's AI spend against the space's daily ceiling per purpose, the
        contract's or the default.


        **Authentication.** Console person token with the `analysis` role (or
        admin), or a source key with the `admin` scope.
      operationId: llm_budget_v1_usage_budget_get
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetReport'
              example:
                items:
                  - purpose: assistant
                    day: '2026-09-22'
                    cap_micros: 200000
                    from_contract: false
                    spent_micros: 41300
                    reached: false
                    resumes_at: null
                  - purpose: extraction
                    day: '2026-09-22'
                    cap_micros: 2000000
                    from_contract: true
                    spent_micros: 2004120
                    reached: true
                    resumes_at: '2026-09-23T00:00:00Z'
          description: 'One line per purpose: `extraction` and `assistant`.'
      security:
        - sourceKey: []
        - personToken: []
components:
  schemas:
    BudgetReport:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/BudgetLine'
          title: Items
          type: array
      required:
        - items
      title: BudgetReport
      type: object
    BudgetLine:
      additionalProperties: false
      properties:
        cap_micros:
          anyOf:
            - type: integer
            - type: 'null'
          description: The daily ceiling, in millionths of a US dollar.
          title: Cap Micros
        day:
          description: The UTC day the spend counts in.
          format: date
          title: Day
          type: string
        from_contract:
          description: True when the contract sets it; false for the cell's default.
          title: From Contract
          type: boolean
        purpose:
          description: '`extraction` or `assistant`.'
          title: Purpose
          type: string
        reached:
          description: Work of this purpose waits for the next UTC day.
          title: Reached
          type: boolean
        resumes_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Resumes At
        spent_micros:
          title: Spent Micros
          type: integer
      required:
        - purpose
        - day
        - cap_micros
        - from_contract
        - spent_micros
        - reached
      title: BudgetLine
      type: object
  securitySchemes:
    sourceKey:
      type: http
      scheme: bearer
      description: nia_sk_...
    personToken:
      type: http
      scheme: bearer
      bearerFormat: JWT

````