Runs and budgets
Cap a job's spending and get one receipt for every call in it.
A run is a budget ceiling plus one receipt. Every paid call belongs to one. If you don't open a run, each call gets its own with a default budget of 1,000 credits ($1).
For a job of several calls, open one run and bill every call to it. Then a loop can't spend more than you meant, and you see the whole job on one receipt.
Open a run
export SUPE_RUN=$(supe budget 2000 --goal "enrich 50 leads" --json | jq -r .run_id)supe budget 2000 opens a run that may spend at most 2,000 credits ($2). --goal is the line you'll see on the receipt. With SUPE_RUN set, every call bills to that run. Use --run <id> to pick a run for one call.
When the run's budget is used up, the next call is refused with run_budget_exceeded (exit 4). Nothing is charged for it.
The receipt
supe receipt $SUPE_RUNdocs · 1 credit spent of 2,000 credits
openalex#works_search 1 credit ok
https://app.oex.sh/activity/run_a45b043e2757supe runs lists recent runs. On the dashboard, Activity shows every run with its steps.
One call, one cap
supe run serper#search --body q=lighthouses --budget 50 --goal "one search"--budget caps the new run this call opens. --max-price refuses the call outright if the tool costs more than that.
Over HTTP and MCP
- HTTP:
POST /v1/runswith{"goal", "budget"}, then passrun_idin eachPOST /v1/run. Or givebudgetandgoalon the firstPOST /v1/runand reuse therun_idit returns.GET /v1/runs/{id}is the receipt. - MCP:
start_run, orbudgetandgoalon the firstexecute_tool; thenrun_idon the rest.get_runis the receipt.
Run budgets sit inside your workspace limits: a call has to fit both.