Skip to content
Hexel StudioDocs

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.

FieldLimitScope
max_usdSpend, in US dollarsThe whole task: a retry gets what earlier attempts left
max_tokensModel tokensThe whole task
max_stepsModel callsEach attempt
max_wall_clock_sSeconds of running timeEach attempt
max_estimate_usdRefuse the task if its estimate is above thisCreate 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.

ErrorMeaning
422 estimate_not_priceableYour organization has no price for the harness: check your plan. Retrying does not help.
503 estimate_unavailableThe 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.

PatternMember runs estimated
mapOne per item, plus the reduce step
pipelineItems × each each stage, plus one per all stage
lead_workersThe lead and one worker per concurrency slot, and at least budget.max_usd
boardThe 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:

ErrorMeaning
403 org_not_in_previewYour organization is not in the private preview.
403 harness_not_in_planYour plan does not include the Titan Harness add-on.
402 insufficient_balance, 402 spending_cap_reached, 402 budget_exceededYour balance, a spending cap or a budget refuses the spend.
402 subscription_inactive, 402 subscription_past_dueYour subscription is not active.
429 too_many_running_tasksYour organization has as many tasks queued, running or waiting as its limit allows.
503 admission_unavailableBilling 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.