---
title: "Run a tool"
method: POST
path: "/tools/{id}/run"
tags: ["Tools"]
---

# Run a tool

`POST /tools/{id}/run`

## Request

- Base URL: `https://api.orcarouter.ai/v1`
- URL: `https://api.orcarouter.ai/v1/tools/{id}/run`
- Auth: HTTP bearer

Execute a tool and return its output with what it cost. The run is
quoted on the most units its input allows, held against the
workspace wallet, the key's quota and any budget, then settled to
the units delivered — never more than 1.25 × the quote. Synchronous.
Limited to 60 runs per minute per key. See
[Run a tool](/agent-infra/tools/run) and
[Errors](/agent-infra/tools/errors).

## Path parameters

- `id` string, required

## Headers

- `X-Orca-Run-Ref` string
- `X-OrcaRouter-Firewall-Approval` string

## Request body

- ToolRunRequest
  - `input` object, required: Validated against the tool's `input_schema`.
  - `approval_id` integer: On the retry of a run a spend policy sent for approval.
  - `wait_ms` integer: Accepted and ignored. Runs are synchronous.

## Response `200`

The run completed.

- object
  - `success` boolean
  - `data` ToolRunResult
    - `run_id` string
    - `status` 'completed'
    - `units` number
    - `quoted_usd` number: The quote, which was held.
    - `billed_usd` number, nullable: What the workspace paid. `null` with `billing` set.
    - `billing` 'pending' | 'unrecorded': `pending`: you will be charged, read the amount later. `unrecorded`: not charged. Absent on an ordinary run.
    - `latency_ms` integer
    - `output` unknown
    - `output_error` string: The provider answered but its result could not be processed; `output` is `null`.
    - `sanitized` boolean
    - `zdr` boolean
    - `budget` object: What is left on budgets that apply. `{}` when none does.
      - `run_left_usd` number
      - `agent_month_left_usd` number

## Other responses

- `400`: A Tools error. Branch on `code`. Refusals from the authentication layer have no `success` or `code`; see [Errors](/agent-infra/tools/errors).
- `402`: A Tools error. Branch on `code`. Refusals from the authentication layer have no `success` or `code`; see [Errors](/agent-infra/tools/errors).
- `403`: A Tools error. Branch on `code`. Refusals from the authentication layer have no `success` or `code`; see [Errors](/agent-infra/tools/errors).
- `404`: A Tools error. Branch on `code`. Refusals from the authentication layer have no `success` or `code`; see [Errors](/agent-infra/tools/errors).
- `413`: The request body exceeded 1 MiB. Empty body.
- `429`: A Tools error. Branch on `code`. Refusals from the authentication layer have no `success` or `code`; see [Errors](/agent-infra/tools/errors).
- `500`: A Tools error. Branch on `code`. Refusals from the authentication layer have no `success` or `code`; see [Errors](/agent-infra/tools/errors).
- `502`: A Tools error. Branch on `code`. Refusals from the authentication layer have no `success` or `code`; see [Errors](/agent-infra/tools/errors).
- `503`: A Tools error. Branch on `code`. Refusals from the authentication layer have no `success` or `code`; see [Errors](/agent-infra/tools/errors).
- `504`: A Tools error. Branch on `code`. Refusals from the authentication layer have no `success` or `code`; see [Errors](/agent-infra/tools/errors).

## Changes

- **2026-11-03** `80ba8288c51d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/orcarouter/apis/orcarouter-api/changes/tools/:id/run/post.md)

---

[API](https://skmtc.dev/orcarouter/apis/orcarouter-api.md) - [All operations](https://skmtc.dev/orcarouter/apis/orcarouter-api/llms.txt) - [OpenAPI document](https://skmtc.dev/orcarouter/apis/orcarouter-api/revisions/80ba8288c51d?raw)