Gateway API

Runs

One agent task is many calls. Name the task, say when it ended, and the Console prices the whole task.

Every call already has a receipt. A run adds them up: send the same run id on every call of a task, and the Console shows what finished tasks cost, by day and by client, and which runs cost the most.

The contract

What	How	Notes
Name the run	`x-lobstack-run-id: <id>` on every call, or `metadata.run_id` in the body	1 to 128 characters: letters, digits, . _ : and -, starting with a letter or digit. A UUID works. The header wins if both are sent.
Finish it on the last call	`x-lobstack-run-status: done`	Or `failed` or `cancelled`. Needs the run id on the same call.
Or finish it afterwards	`POST /runs/{id}/finish`	Body `{"status": "done"}`, with the same API key. For a task that ends after its last model call.

A malformed run id or status is a 400 with error_code: "RUN_ID_INVALID", before anything is spent. A call dropped from its run would make the run look cheaper than it was.

Every call of the taskbash

curl https://www.lobstack.ai/api/gateway/v1/chat/completions \
  -H "Authorization: Bearer $LOBSTACK_API_KEY" \
  -H "x-lobstack-run-id: $RUN_ID" \
  -d '{ "model": "auto", "messages": [...] }'

When the task endsbash

curl -X POST https://www.lobstack.ai/api/gateway/v1/runs/$RUN_ID/finish \
  -H "Authorization: Bearer $LOBSTACK_API_KEY" \
  -d '{"status": "done"}'

Finishing

The first finish wins. A repeat answers 200 with already_finished: true and the status that was stored, so a client can retry it. A run id is looked up only inside the key's own organization.

A run with no finish is open. Open runs are listed, and never counted in the cost per finished run.

How a run is priced

A run's cost is the sum of cost_usd on every ledger row that carries its id, whenever the call was made. Failed calls are rows too, at whatever they cost. If any call could not be priced, the run's cost is unknown: it is shown as a dash and left out of the median and p90 rather than read as cheaper.

The Console groups finished runs by the day they finished and by client tag. See Performance.