> ## 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. # List budgets > Returns budgets visible to the current workspace, ordered by creation time with the newest first. Supports filtering by scope kind, scope target id, period, and active state, plus an optional free-text query that searches across denormalized target names via Typesense. ## OpenAPI ````yaml get /v2/budgets 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: get: tags: - Budgets summary: List budgets description: >- Returns budgets visible to the current workspace, ordered by creation time with the newest first. Supports filtering by scope kind, scope target id, period, and active state, plus an optional free-text query that searches across denormalized target names via Typesense. operationId: BudgetList parameters: - name: limit in: query description: Page size, 1–200. Unset uses the server default (25). schema: type: integer format: int32 - name: starting_after in: query description: |- Cursor for forward pagination. Set to the `budget_id` of the last item from the previous page. schema: type: string - name: ending_before in: query description: |- Cursor for backward pagination. Set to the `budget_id` of the first item from the previous page. schema: type: string - name: scope_kind in: query description: |- Optional filter: only return budgets whose scope kind matches one of the listed values. Empty means no scope-kind filter. schema: type: array items: $ref: '#/components/schemas/BudgetScopeKind' - name: scope_target_id in: query description: 'Optional filter: only return budgets whose scope target id matches.' schema: type: string - name: is_active in: query description: 'Optional filter: only return budgets with this active state.' schema: type: boolean - name: period in: query description: |- Optional filter: only return budgets whose limits.period matches one of the listed values. Empty means no period filter. schema: type: array items: $ref: '#/components/schemas/BudgetPeriod' - name: query in: query description: |- Optional free-text query. Server translates this into a Typesense search over the denormalized `scope_target_name` and id fields on the per-workspace `{workspace_id}_budgets` collection. schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ListBudgetsResponse' components: schemas: BudgetScopeKind: type: string enum: - BUDGET_SCOPE_KIND_UNSPECIFIED - BUDGET_SCOPE_KIND_WORKSPACE - BUDGET_SCOPE_KIND_PROJECT - BUDGET_SCOPE_KIND_IDENTITY - BUDGET_SCOPE_KIND_API_KEY - BUDGET_SCOPE_KIND_PROVIDER - BUDGET_SCOPE_KIND_MODEL BudgetPeriod: type: string enum: - BUDGET_PERIOD_UNSPECIFIED - BUDGET_PERIOD_DAILY - BUDGET_PERIOD_WEEKLY - BUDGET_PERIOD_MONTHLY - BUDGET_PERIOD_YEARLY - BUDGET_PERIOD_ONE_TIME ListBudgetsResponse: type: object properties: object: type: string description: Object discriminator for list responses; always `list`. data: type: array items: $ref: '#/components/schemas/Budget' description: Page of budgets, ordered newest first. has_more: type: boolean description: |- Whether more budgets are available in the selected pagination direction. Budget: type: object properties: budget_id: type: string workspace_id: type: string scope: $ref: '#/components/schemas/BudgetScope' limits: $ref: '#/components/schemas/BudgetLimits' rate_limit: $ref: '#/components/schemas/RateLimit' is_active: type: boolean expires_at: format: date-time type: string created_at: format: date-time type: string updated_at: format: date-time type: string description: |- Budget is the canonical record stored in MongoDB `budgets.entities`. It replaces the embedded `constraints.budget` on api-keys and the legacy CONTACT-only `budgets.configs` collection (see ADR 0007). BudgetScope: type: object properties: workspace: $ref: '#/components/schemas/WorkspaceBudgetScope' project: $ref: '#/components/schemas/ProjectBudgetScope' identity: $ref: '#/components/schemas/IdentityBudgetScope' api_key: $ref: '#/components/schemas/ApiKeyBudgetScope' provider: $ref: '#/components/schemas/ProviderBudgetScope' model: $ref: '#/components/schemas/ModelBudgetScope' description: |- BudgetScope is a closed oneof. Exactly one variant must be set. The six variants are ordered by enforcement precedence (most specific to most general) and mirror the BudgetScopeKind filter enum. BudgetLimits: type: object properties: period: $ref: '#/components/schemas/BudgetPeriod' amount: type: number format: double token_limit: type: string description: |- BudgetLimits is the per-period spend and token ceiling. At least one of `amount`, `token_limit`, or RateLimit.requests_per_minute MUST be set on a Budget; that invariant is enforced by the handler. RateLimit: type: object properties: requests_per_minute: type: integer format: int32 description: |- RateLimit is the per-minute request ceiling. Enforced via atomic increment-first semantics in the enforcement middleware. WorkspaceBudgetScope: type: object properties: {} description: Workspace-wide ceiling. The implicit target is the caller's workspace. ProjectBudgetScope: type: object properties: project_id: type: string description: Per-project cap. IdentityBudgetScope: type: object properties: identity_external_id: type: string description: |- Per-identity cap. Keyed by the contact's external_id (not the internal Mongo `_id`) so the scope is stable across imports. ApiKeyBudgetScope: type: object properties: api_key_id: type: string description: |- Per-api-key cap. Replaces the legacy embedded `constraints.budget` on auth.apiKeys. ProviderBudgetScope: type: object properties: provider: type: string description: |- Per-provider cap. The value is the provider enum string (e.g. "openai", "anthropic") drawn from ModelIntegrationIdentifier. ModelBudgetScope: type: object properties: model_id: type: string description: |- Per-model cap. The value is the provider-issued literal model_id (e.g. "gpt-4o") — NOT the Mongo `_id` of the model master-data document — so the scope is stable across workspaces. securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: JWT ````