---
title: "Run custom tool"
method: POST
path: "/v1/custom-tools/{id}/run"
tags: ["custom_tools"]
---

# Run custom tool

`POST /v1/custom-tools/{id}/run`

Executes a custom code tool with the given parameters and returns its result. The code runs in the sandbox exactly as an agent would invoke it. A tool whose own code fails still returns 200 with `success: false`; a non-2xx only means the tool was not found or the arguments were rejected. Requires a token with write access.

## Path parameters

- `id` string, required — Custom tool id.

## Request body

- object — Request body for running a custom code tool. Requires a token with write access since execution can have side effects.
  - `workspace_id` string — Optional workspace override. If omitted, Conduit resolves the tool's workspace automatically.
  - `parameters` object — Arguments passed to the tool's `main` entrypoint, keyed by parameter name. Every parameter the tool marks as `required` must be present.

## Response `200`

Custom tool run result

- object — Result of executing a custom code tool. A non-2xx is only returned when the tool could not be found or the arguments were rejected; a tool whose code fails returns 200 with `success: false`.
  - `data` object, required
    - `success` boolean, required — Whether the tool's code ran to completion and returned the expected shape. `false` means the code threw or returned an invalid result; see `error`.
    - `message` string, nullable, required — The `message` string the tool returned, if any.
    - `result` unknown
    - `error` string, nullable, required — Failure reason when `success` is false, otherwise null.
    - `logs` string, nullable, required — Captured stdout/stderr from the run, if any.
    - `run_time_ms` number, required — Wall-clock execution time in milliseconds.

## Other responses

- `400` — Invalid request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not found
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/conduit/apis/conduit-api.md) · [All operations](https://skmtc.net/conduit/apis/conduit-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/conduit/conduit-api/versions/3ad7e17f96ad/schema)