Skip to navigation
AgentRouter APIRuns

Invoke a tool

View as Markdown

Validates the input against the tool’s schema, checks that pricing_version is still current, reserves the maximum charge (bounded by max_cost_usd and your budgets) and runs the tool. The server waits up to wait_ms (default and maximum 25 seconds); a run that is still going returns 202 and keeps running server-side — poll GET /v1/runs/{run_id} instead of invoking again.

Send an Idempotency-Key header (or idempotency_key) to make retries safe: the same key with the same request returns the original run with replayed: true and billing.charge_is_new: false; the same key with a different request is rejected.

Requests rejected before a run is created (invalid input, stale pricing_version, unknown tool) execute nothing and charge nothing. Runs blocked by balance, budgets or limits are recorded with status BLOCKED and are not charged.

Authentication

AuthorizationBearer
An AgentRouter API key or an OAuth access token issued to an MCP host or the CLI.

Headers

Idempotency-KeystringOptional<=200 characters

Client-chosen key (at most 200 characters) that makes retries return the original run.

Request

This endpoint expects an object.
tool_idstringRequired
pricing_versionstringRequired

From describe. A changed price is refused (PRICING_CHANGED) instead of charged.

inputmap from strings to any or list of anyOptional

Matches the tool’s input_schema (an object or an array).

tool_versionstringOptional

Optional pin; refused with TOOL_VERSION_CHANGED if the tool changed.

max_cost_usdstringOptionalformat: "^-?[0-9]+(\.[0-9]+)?$"

Most you allow this call to cost. Default 0.50, lowered by budgets’ per-call maximums.

session_idstringOptional<=128 characters

Groups runs of one agent task; session budgets apply.

idempotency_keystringOptional<=200 characters

Same as the Idempotency-Key header.

wait_msintegerOptional0-25000
How long the request waits before returning 202.

Response

The run finished (COMPLETED, FAILED, STOPPED or TIMED_OUT). Charges follow billing.reason.

objectany
run_idstring
statusenum
tool_idstring
tool_versionstring
providerstring
inputany
The submitted tool input
session_idstring or null
callerobject
channelenum
Allowed values:
created_atstring or null
started_atstring or null
completed_atstring or null
latency_msinteger or null
replayedboolean
True when an idempotency key returned an existing run.
stoppableboolean
provider_responseobject
errorobject or null
billingobject
resultobject
next_cursorstring or null

Pass back as the tool’s cursor input for the next page (a new billed call).

hintslist of objects
outputany
The provider's output exactly as returned

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error