Sign in

v2

latestOpenAPI 3.1.02026-08-05267431678.1 KB
auto-agent

Report Agent Turn Billing

Accept a legacy per-turn LLM self-report from inside the sandbox.

Brokered sandboxes now bill the upstream LLM call server-side on /v1/messages from Brain-observed usage. This endpoint remains for older sandbox images and verifies the callback token, but it does not create a second billing row from sandbox-supplied tokens.

Auth: the same one-time X-Callback-Token issued at run creation that gates the other /auto-agent/run/{run_id}/... callbacks. No bearer token / API key is involved — the sandbox runs untrusted code and intentionally has no credentials beyond this token.

Dedup: (run_id, body.turn_id) is cached in dedup_cache so any legacy end-of-run replay treats the self-report as handled.

Args: run_id: Run UUID from the path. body: Per-turn token usage payload. callback_token: Sandbox callback token from X-Callback-Token header.

Raises: HTTPException 401: Callback token invalid or run finalized. HTTPException 404: Run not found.

post/auto-agent/run/{run_id}/billing/agent-turn

Path parameters

run_idstring required

Headers

X-Callback-Tokenstring required

Request body

turn_idstring required

Sandbox-supplied dedup key for this turn (UUID recommended).

providerstring required
modelstring required
input_tokensinteger
output_tokensinteger

Response

Successful Response

request_idstring nullable

Normally null for accepted compatibility self-reports; may contain a cached legacy requests row id for old dedup entries.

billedboolean required

False for accepted compatibility self-reports; brokered sandbox LLM usage is billed server-side on /v1/messages.