Running endpoints: envelope, response controls, max cost
POST /v1/run/{endpoint_id} with the endpoint's input as the JSON body. Endpoint ids and schemas: GET /v1/catalog/{endpoint_id}.
Response controls (shape the output, never the cost)
| Query parameter | Effect |
|---|---|
fields=summary.score,actions.action | Keep only these (dotted) paths; lists of objects are filtered per item |
max_items=5 | Cap every list; _truncated reports how many rows were withheld per path |
summary=true | Return an outline (type, item count, bytes per top-level key) instead of the data |
jq=… | Accepted but not executed on this server: full output returned with jq_error |
A large unshaped response carries hint: "large_result: …".
Cost guard
max_cost_usd=0.50 refuses the call before it runs if it would cost more (402 max_cost_exceeded, nothing charged, message states the price).
Idempotency
Send Idempotency-Key: <your id> on paid calls. Same key + same body within 24 h → original response, no new charge, Idempotency-Replayed: true. Same key + different body → 409 idempotency_conflict. Same key while the first call is still running → 409 idempotency_in_progress (retry after Retry-After). Failed calls are not cached.
Quote first
POST /v1/quote/{endpoint_id} validates the input and returns cost_usd, available, and with a key balance_usd, limit_remaining_usd, can_run. Free; nothing runs.
Plain Markdown for agents: /docs/running.md · index: llms.txt