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

# Budgets

> List and inspect organization and department budgets.

## List budgets

Returns a cursor-paginated list of budgets for your organization.

```bash theme={null}
GET /v1/budgets
```

<ParamField query="cursor" type="string">
  Opaque pagination cursor. Pass `next_cursor` from a previous response to fetch the next page. Omit for the first page.
</ParamField>

<ParamField query="limit" type="integer" default="25">
  Maximum items per page (1–100).
</ParamField>

### Request

```bash theme={null}
curl https://api.toktra.io/v1/budgets \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Response

```json theme={null}
{
  "items": [
    {
      "id": "b3c1e9f2-1234-5678-abcd-000000000001",
      "org_id": "a1b2c3d4-0000-0000-0000-000000000000",
      "name": "Engineering Monthly",
      "department": "engineering",
      "amount": 50000.00,
      "spent": 32150.75,
      "remaining": 17849.25,
      "currency": "USD",
      "period": "monthly",
      "hard_cap": true,
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ],
  "next_cursor": "eyJpZCI6ImIzYzFlOWYyIn0",
  "has_more": true,
  "total_count": 8
}
```

***

## Get budget

Returns a single budget by ID.

```bash theme={null}
GET /v1/budgets/{id}
```

<ParamField path="id" type="string" required>
  Budget UUID.
</ParamField>

### Request

```bash theme={null}
curl https://api.toktra.io/v1/budgets/b3c1e9f2-1234-5678-abcd-000000000001 \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Response

```json theme={null}
{
  "id": "b3c1e9f2-1234-5678-abcd-000000000001",
  "org_id": "a1b2c3d4-0000-0000-0000-000000000000",
  "name": "Engineering Monthly",
  "department": "engineering",
  "amount": 50000.00,
  "spent": 32150.75,
  "remaining": 17849.25,
  "currency": "USD",
  "period": "monthly",
  "hard_cap": true,
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}
```

***

## Budget object

<ResponseField name="id" type="string">
  Unique budget identifier (UUID).
</ResponseField>

<ResponseField name="org_id" type="string">
  Organization that owns this budget.
</ResponseField>

<ResponseField name="name" type="string">
  Human-readable budget name.
</ResponseField>

<ResponseField name="department" type="string">
  Department this budget applies to. `null` for org-wide budgets.
</ResponseField>

<ResponseField name="amount" type="number">
  Budget limit for the current period, in `currency`.
</ResponseField>

<ResponseField name="spent" type="number">
  Amount consumed in the current period.
</ResponseField>

<ResponseField name="remaining" type="number">
  `amount` minus `spent`.
</ResponseField>

<ResponseField name="currency" type="string">
  ISO 4217 currency code (e.g., `USD`).
</ResponseField>

<ResponseField name="period" type="string">
  Budget period: `daily`, `weekly`, `monthly`, `quarterly`, or `annual`.
</ResponseField>

<ResponseField name="hard_cap" type="boolean">
  When `true`, LLM requests are blocked once `remaining` reaches zero. When `false`, usage is allowed but an alert is triggered.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 last-updated timestamp.
</ResponseField>

<Note>
  To create or modify budgets, use the dashboard under **Budgets** or the [Terraform provider](/integrations/terraform).
</Note>