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

# Budget

> Inspect and update your org's spend cap and credit alert thresholds.

Inspect and update your org's spend cap and credit alert thresholds. Both endpoints require the `control:read` scope.

Model access (which models your org can use, its default, provider and fallback routing) is a separate concern — see [Model access](/ai-api/control/model-access) and [Models](/ai-api/control/models).

***

## Get budget settings

```
GET https://api.usehasp.com/v1/usage/budget
Authorization: Bearer hasp_api_live_...
```

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "spend_cap": 50000,
    "alert_thresholds": [75, 90],
    "credits_allotment": 100000
  }
}
```

### Fields

| Field               | Description                                                                                                                                                       |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `spend_cap`         | Credit cap for this billing cycle. Requests return `402 AI_CREDITS_EXHAUSTED` when credits used reaches this value. `null` means no cap (full allotment applies). |
| `alert_thresholds`  | Sorted list of percentage integers (1–100) at which usage notifications are sent. Empty array means no alerts configured. Max 3 thresholds.                       |
| `credits_allotment` | Total credits available this cycle (read-only — set by your plan).                                                                                                |

***

## Update budget settings

```
PATCH https://api.usehasp.com/v1/usage/budget
Authorization: Bearer hasp_api_live_...
Content-Type: application/json
```

All fields are optional. Send only what you want to change. An empty body returns the current state without modifying anything.

### Body

```json theme={null}
{
  "spend_cap": 50000,
  "alert_thresholds": [75, 90]
}
```

| Field              | Type            | Description                                                                                        |
| ------------------ | --------------- | -------------------------------------------------------------------------------------------------- |
| `spend_cap`        | integer or null | Credit cap. Min `0`. Set `null` to remove the cap.                                                 |
| `alert_thresholds` | array or null   | Percentage integers, each 1–100. Max 3 entries. Sorted automatically. Set `[]` or `null` to clear. |

### Response

Returns the updated budget state in the same shape as the GET response.

```json theme={null}
{
  "success": true,
  "data": {
    "spend_cap": 50000,
    "alert_thresholds": [75, 90],
    "credits_allotment": 100000
  }
}
```

Every successful update is recorded in the audit log with `action: budget.updated`.

***

## Error codes

| Code                | HTTP | Description                                                                   |
| ------------------- | ---- | ----------------------------------------------------------------------------- |
| `INVALID_API_KEY`   | 401  | Invalid or revoked token                                                      |
| `MISSING_SCOPE`     | 403  | Key lacks `control:read` scope                                                |
| `VALIDATION_FAILED` | 422  | `spend_cap` is negative; threshold out of 1–100 range; more than 3 thresholds |