# Running endpoints

`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.
