POST /v1/run

Execute a specific provider endpoint. Billed.

Sync tools return the completed run immediately (200). Async tools return 202 with a runId — poll GET /v1/runs/get.

Request

POST /v1/run

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <api-key>`
`Content-Type`	Yes	`application/json`

Body

Field	Type	Required	Description
`provider`	string	Yes	Provider slug
`endpoint`	string	Yes	Endpoint slug
`input`	object	No	JSON body (default `{}`)

Example

curl -X POST https://api.toolplexer.com/v1/run \
  -H "Authorization: Bearer tpl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "exa",
    "endpoint": "/search",
    "input": { "query": "AI agent tooling", "maxResults": 5 }
  }'

Response

Field	Type	Description
`runId`	string
`provider`	string
`slug`	string	Endpoint slug
`status`	string	`READY` `RUNNING` `COMPLETED` `FAILED` `BLOCKED` `STOPPED` `TIMED_OUT`
`output`	any \| null	Provider output
`error`	string \| null
`errorSource`	`"provider"` \| `"platform"` \| null
`providerHttpStatus`	number \| null	Upstream HTTP status
`stoppable`	boolean	`true` only while `READY`
`holdUsdMicro`	number	Amount held
`costUsdMicro`	number \| null	Amount charged
`billedUnits`	number \| null
`controls`	array \| null	Present when `BLOCKED`
`hints`	array

Status vs provider HTTP status

status — did our run finish? COMPLETED means the provider was called. FAILED is our fault. BLOCKED never called the provider.
providerHttpStatus — did the provider return data? 200 = yes. 404 = no match. Not charged on >= 400.

Do not automatically retry paid operations.

Poll GET /v1/runs/get for async runs. Prefer POST /v1/execute when you want ToolPlexer to pick the provider.