Budgets and estimates
Limit what a task may spend, price a task or a swarm before it starts, and understand how the harness admits work.
On this page
Budgets
A task's budget limits what it may use. Each limit narrows the agent's own budgets from its 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) |
hexel harness task create "Audit the api repo" --agent auditor \
--budget-usd 5 --max-steps 120 --max-seconds 3600A 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.
hexel harness task resume tsk_123 --budget-usd 10While 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.
hexel harness task estimate --agent auditor@prod --max-estimate-usd 5curl -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}}'{"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 itsmax_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, withrefusal(for exampleinsufficient_balance) andreasons. - Your ceiling. Above
max_estimate_usd, the answer haswithin_budget: falseandrefusal: 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 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 has the numbers.