---
title: "Get budget status"
method: GET
path: "/api/v1/budgets/{id}/status"
tags: ["Cost Controls"]
---

# Get budget status

`GET /api/v1/budgets/{id}/status`

## Request

- Base URL: `https://orchestrator.getaxonflow.com`
- URL: `https://orchestrator.getaxonflow.com/api/v1/budgets/{id}/status`
- Auth: none declared
- TypeScript: <https://skmtc.dev/getaxonflow/apis/axonflow-orchestrator-api/docs/api/v1/budgets/:id/status/get.ts> (a function with typed inputs; its response is checked against the schema)

Get real-time status of a budget including current usage,
remaining amount, and whether the budget is exceeded.

Enterprise only. These routes are not registered in Community
edition, which returns 404 Not Found.

## Path parameters

- `id` string, required

## Response `200`

Budget status

- BudgetStatus
  - `budget` Budget
    - `id` string, required: Unique budget identifier
    - `name` string, required: Human-readable budget name
    - `enabled` boolean: When false the budget is configured but its limit is not enforced — usage is still tracked. Lets operators dry-run a budget before flipping it on.
    - `scope` 'organization' | 'team' | 'agent' | 'workflow' | 'user', required: Budget scope level
    - `scope_id` string: ID of the scoped entity (team_id, agent_id, etc.)
    - `limit_usd` number, double, required: Maximum spending limit in USD
    - `period` 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'yearly', required: Budget reset period
    - `on_exceed` 'warn' | 'block' | 'downgrade': Action when budget is exceeded
    - `alert_thresholds` integer[]: Percentage thresholds for alerts (e.g., [50, 80, 100])
    - `org_id` string: Organization ID
    - `tenant_id` string: Tenant ID (multi-tenant deployments)
    - `created_at` string, date-time
    - `updated_at` string, date-time
  - `used_usd` number, double: Amount spent in current period
  - `remaining_usd` number, double: Remaining budget
  - `percentage` number, double: Percentage of budget used
  - `period_start` string, date-time
  - `period_end` string, date-time
  - `is_exceeded` boolean: Whether budget limit has been exceeded
  - `is_blocked` boolean: Whether requests are being blocked

## Other responses

- `404`: Budget not found

---

[API](https://skmtc.dev/getaxonflow/apis/axonflow-orchestrator-api.md) - [All operations](https://skmtc.dev/getaxonflow/apis/axonflow-orchestrator-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getaxonflow/apis/axonflow-orchestrator-api/revisions/f408ef3ec9dd?raw)