Skip to Content
supedocs

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_RUN
docs  ·  1 credit spent of 2,000 credits
  openalex#works_search                        1 credit  ok
https://app.oex.sh/activity/run_a45b043e2757

supe 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/runs with {"goal", "budget"}, then pass run_id in each POST /v1/run. Or give budget and goal on the first POST /v1/run and reuse the run_id it returns. GET /v1/runs/{id} is the receipt.
  • MCP: start_run, or budget and goal on the first execute_tool; then run_id on the rest. get_run is the receipt.

Run budgets sit inside your workspace limits: a call has to fit both.

On this page