---
title: Budgets and estimates
description: Limit what a task may spend, price a task or a swarm before it
  starts, and understand how the harness admits work.
url: https://hexelstudio.com/docs/harness/budgets-and-estimates
---

## Budgets

A task's `budget` limits what it may use. Each limit narrows the agent's own `budgets` from its [spec bundle](https://hexelstudio.com/docs/harness/agents#the-spec-bundle): the smaller of the two applies.

| Field | Limit | Scope |
| --- | --- | --- |
| `max_usd` | Spend, in US dollars | The whole task: a retry gets what earlier attempts left |
| `max_tokens` | Model tokens | The whole task |
| `max_steps` | Model calls | Each attempt |
| `max_wall_clock_s` | Seconds of running time | Each attempt |
| `max_estimate_usd` | Refuse the task if its estimate is above this | Create only (below) |

```bash
hexel harness task create "Audit the api repo" --agent auditor \
  --budget-usd 5 --max-steps 120 --max-seconds 3600
```

A task that reaches its budget stops as `budget_exhausted`. Resume it with a new budget; a resume or retry with a budget it has already used is refused with `409`.

```bash
hexel harness task resume tsk_123 --budget-usd 10
```

While it runs, the task's stream reports `cost.update` `{usd, tokens_in, tokens_out}` and, for each model call, `model.usage`. `GET /harness/tasks/{id}` shows `cost_usd`.

## Estimates

An estimate prices a task the way creating it would, and checks whether billing would admit it. It creates, reserves and charges nothing.

```bash
hexel harness task estimate --agent auditor@prod --max-estimate-usd 5
```

```bash
curl -X POST https://api.hexelstudio.com/v1/harness/tasks:estimate \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID" -H "X-Environment-Id: $ENVIRONMENT_ID" \
  -H "Content-Type: application/json" \
  -d '{"agent": "auditor@prod", "budget": {"max_estimate_usd": 5}}'
```

```json
{"members": 1, "per_member_usd": 0.15, "usd": 0.15, "quantity": 50000,
 "meter": "harness.model_input_tokens", "source": "default",
 "max_estimate_usd": 5, "within_budget": true,
 "admitted": true, "decision_id": "dec_..."}
```

- **How it is priced.** One run's cost is the agent version's mean run cost when it has statistics (`source: stats`), otherwise 50,000 model input tokens (`source: default`). Your organization's own prices apply. The estimate is a starting point, not a quote: a task can cost more or less, up to its `max_usd`.
- **Admission.** Billing is asked whether it would admit the whole estimate (balance, spending caps and budgets). A refusal is reported, not raised: `admitted: false`, with `refusal` (for example `insufficient_balance`) and `reasons`.
- **Your ceiling.** Above `max_estimate_usd`, the answer has `within_budget: false` and `refusal: estimate_over_budget`.

On `POST /harness/tasks`, `budget.max_estimate_usd` refuses a task whose estimate is above it with `422 estimate_over_budget` (the estimate is in the body), before anything is created or charged.

| Error | Meaning |
| --- | --- |
| `422 estimate_not_priceable` | Your organization has no price for the harness: check your plan. Retrying does not help. |
| `503 estimate_unavailable` | The price cannot be checked now. Try again after `Retry-After`. |

### Swarms

`POST /harness/swarms:estimate` (`hexel harness swarm estimate -f swarm.yaml`) takes the body a [swarm](https://hexelstudio.com/docs/harness/swarms) takes and prices the whole swarm before any member starts: every member run it may make, including the retries its failure rule allows.

| Pattern | Member runs estimated |
| --- | --- |
| `map` | One per item, plus the reduce step |
| `pipeline` | Items × each `each` stage, plus one per `all` stage |
| `lead_workers` | The lead and one worker per concurrency slot, and at least `budget.max_usd` |
| `board` | The board's members, or each item × its attempts when more, and at least `budget.max_usd` |

A swarm's `budget.max_estimate_usd` refuses it the same way. A `lead_workers` or `board` swarm whose `max_estimate_usd` is below its `max_usd` is always refused: its size is not known before it starts.

## How work is admitted

Creating a task, and resuming or retrying one, is checked before anything changes:

| Error | Meaning |
| --- | --- |
| `403 org_not_in_preview` | Your organization is not in the private preview. |
| `403 harness_not_in_plan` | Your plan does not include the Titan Harness add-on. |
| `402 insufficient_balance`, `402 spending_cap_reached`, `402 budget_exceeded` | Your balance, a spending cap or a budget refuses the spend. |
| `402 subscription_inactive`, `402 subscription_past_due` | Your subscription is not active. |
| `429 too_many_running_tasks` | Your organization has as many tasks queued, running or waiting as its limit allows. |
| `503 admission_unavailable` | Billing or limits could not be checked; try again after `Retry-After`. Work is never admitted unchecked. |

A paused task holds no capacity, so its resume is checked like a new task. [Limits and pricing](https://hexelstudio.com/docs/harness/limits-and-pricing) has the numbers.
