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

# Check budget enforcement

> Internal endpoint used by the gateway to resolve applicable budgets and check enforcement gates for a request. Returns allowed/rejected status with dimension info for rate-limit headers.



## OpenAPI

````yaml post /v2/budgets/check
openapi: 3.1.0
info:
  title: orq.ai API
  version: '2.0'
  description: orq.ai API documentation
servers:
  - url: https://api.orq.ai
security:
  - ApiKey: []
tags:
  - description: List models available through the AI Router.
    name: Models
  - name: Guardrail Rules
  - name: Policies
  - name: Routing Rules
  - name: API keys
    description: >-
      API keys authenticate programmatic access to the workspace. The unified
      key model exposes opaque tokens, per-domain access grants, and budget /
      rate-limit constraints (see ADR 0001 and ADR 0002).
  - name: Budgets
    description: >-
      Budgets govern spend, token usage, and request rate across six scopes:
      workspace, project, identity, api-key, provider, and model. A budget is
      hierarchical and defense-in-depth — every applicable budget is a hard
      gate, and the most restrictive one wins per dimension (see ADR 0007).
  - name: Documentation
    description: >-
      Search the orq.ai documentation. Proxies the workspace's query to the
      hosted docs search index.
  - name: Files
    description: File upload and retrieval operations.
  - name: Identities
    description: >-
      Identities represent end users from your system for usage and engagement
      tracking.
  - name: Projects
    description: Projects organize resources within a workspace
  - name: Skills
    description: >-
      Skills are modular instructions you can use to codify processes and
      conventions
  - name: Responses
  - description: >-
      Run agents on a cadence — cron, interval, or one-off. Minimum firing
      interval is 1 hour.
    name: Agent Schedules
  - name: Embeddings
  - name: Reporting
    description: >-
      GenAI reporting API over canonical analytics rollups. Accepts a metric
      name, time range, grain, group-by, and filters; returns a typed time
      series and optional totals.
externalDocs:
  url: https://docs.orq.ai
  description: orq.ai Documentation
paths:
  /v2/budgets/check:
    post:
      tags:
        - Budgets
      summary: Check budget enforcement
      description: >-
        Internal endpoint used by the gateway to resolve applicable budgets and
        check enforcement gates for a request. Returns allowed/rejected status
        with dimension info for rate-limit headers.
      operationId: BudgetCheck
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckBudgetsRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckBudgetsResponse'
components:
  schemas:
    CheckBudgetsRequest:
      type: object
      properties:
        workspace_id:
          type: string
          description: Workspace the request belongs to.
        api_key_id:
          type: string
          description: API key that issued the request (if any).
        project_id:
          type: string
          description: Project the request targets (if any).
        identity_external_id:
          type: string
          description: Identity external id for contact-scoped budgets (if any).
        provider:
          type: string
          description: Provider enum value for provider-scoped budgets (if any).
        model_id:
          type: string
          description: Literal provider model_id for model-scoped budgets (if any).
    CheckBudgetsResponse:
      type: object
      properties:
        allowed:
          type: boolean
          description: True when no applicable budget exceeds its limit.
        rejection:
          allOf:
            - $ref: '#/components/schemas/BudgetRejection'
          description: |-
            Populated when allowed is false; identifies which budget and
             dimension triggered the rejection.
        cost:
          allOf:
            - $ref: '#/components/schemas/DimensionInfo'
          description: >-
            Cost dimension info for rate-limit headers (nil when no cost budget
            applies).
        tokens:
          allOf:
            - $ref: '#/components/schemas/DimensionInfo'
          description: >-
            Token dimension info for rate-limit headers (nil when no token
            budget applies).
        requests:
          allOf:
            - $ref: '#/components/schemas/DimensionInfo'
          description: >-
            Requests dimension info for rate-limit headers (nil when no RPM
            budget applies).
    BudgetRejection:
      type: object
      properties:
        scope_kind:
          type: string
        scope_target_id:
          type: string
        dimension:
          type: string
        code:
          type: string
        message:
          type: string
      description: BudgetRejection identifies the budget that caused a 429.
    DimensionInfo:
      type: object
      properties:
        limit:
          type: number
          format: double
        remaining:
          type: number
          format: double
        reset_seconds:
          type: integer
          format: int32
      description: DimensionInfo carries limit/remaining/reset for a single dimension.
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: JWT

````