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

# Budget reservations

> Reserve spend against organization and group budgets before an action runs.

A budget check made **after** an action runs can only report an overspend. A
reservation holds the estimated cost **before** the action runs, so concurrent
agents cannot all pass the same check and overshoot the budget together.

The Python SDK does this for you when you use
[`RemoteCostBackend`](https://docs.agentsentinel.dev/sdk/python/cost-tracking#platform-budgets-remotecostbackend).
Call the endpoint directly if you are integrating from another language.

## POST /api/v1/budgets/reserve

Atomically checks the caller's organization monthly budget and, when `group_id` is
set, that group's budget, then holds `estimated_cost_usd` against both for
**15 minutes**.

Requires an API key or session in an organization context.

### Request

```json theme={null}
{
  "action_name": "call_llm",
  "estimated_cost_usd": 0.25,
  "group_id": "customer-acme",
  "run_id": "6f1c2c5e-6a8e-4c39-9b0e-0d6f3f6d2a11"
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `action_name` | string | yes | Action the spend is for |
| `estimated_cost_usd` | number | yes | Amount to hold |
| `group_id` | string | no | Also check and hold against this group's budget |
| `run_id` | UUID string | no | Run to associate the hold with |

### Response: `201 Created`

```json theme={null}
{
  "reservation_id": "0b8d6a8e-3f3e-4a8f-9a57-5c7f0f3c1d2e",
  "remaining_usd": 41.75
}
```

`remaining_usd` is the smallest headroom left across the budgets that were
checked, or `null` when neither has a limit configured.

### Response: `402 Payment Required`

The hold would exceed a budget. Nothing is reserved.

```json theme={null}
{
  "detail": {
    "error": "group_budget_exceeded",
    "budget_type": "group",
    "group_id": "customer-acme",
    "spent": 50.10,
    "limit": 50.0
  }
}
```

`budget_type` is `organization_monthly` (with `error: "monthly_budget_exceeded"`)
or `group`. `spent` is the projected total including this request.

### Other errors

| Status | Cause |
| - | - |
| `400` | No organization context, or `run_id` is not a UUID |
| `401` | Missing or invalid credentials |

## Settling a reservation

Send the `reservation_id` on the matching ledger entry when you
[ingest](https://docs.agentsentinel.dev/platform/ingest.md) it. Ingest swaps the held estimate for the entry's
actual `cost_usd`, so the spend is not counted twice. A hold that is never
settled stops counting against the budget once its 15 minutes are up.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.