---
title: "Execute Tool"
method: POST
path: "/v1/tools/execute"
tags: ["Tools"]
---

# Execute Tool

`POST /v1/tools/execute`

Executes a tool by name and arguments

## Request body

- SchemasExecuteToolRequest
  - `include_error_stacktrace` boolean — Whether to include the error stacktrace in the response. If not provided, the error stacktrace is not included.
  - `input` ToolRawInputs
  - `run_at` string — The time at which the tool should be run (optional). If not provided, the tool is run immediately. Format ISO 8601: YYYY-MM-DDTHH:MM:SS
  - `tool_name` string, required
  - `tool_version` string — The tool version to use (optional). If not provided, any version is used
  - `user_id` string

## Response `200`

OK

- SchemasExecuteToolResponse
  - `duration` number
  - `execution_id` string
  - `execution_type` string
  - `finished_at` string
  - `id` string
  - `output` ToolResponseOutput
    - `authorization` AuthAuthorizationResponse
      - `context` AuthAuthorizationContext
        - `token` string
        - `user_info` object
      - `id` string
      - `provider_id` string
      - `scopes` string[]
      - `status` 'not_started' | 'pending' | 'completed' | 'failed'
      - `url` string
      - `user_id` string
    - `error` ToolError
      - `additional_prompt_content` string
      - `can_retry` boolean, required
      - `developer_message` string
      - `extra` object
      - `kind` 'TOOLKIT_LOAD_FAILED' | 'TOOL_DEFINITION_BAD_DEFINITION' | 'TOOL_DEFINITION_BAD_INPUT_SCHEMA' | 'TOOL_DEFINITION_BAD_OUTPUT_SCHEMA' | 'TOOL_REQUIREMENTS_NOT_MET' | 'TOOL_RUNTIME_BAD_INPUT_VALUE' | 'TOOL_RUNTIME_BAD_OUTPUT_VALUE' | 'TOOL_RUNTIME_RETRY' | 'TOOL_RUNTIME_CONTEXT_REQUIRED' | 'TOOL_RUNTIME_FATAL' | 'CONTEXT_CHECK_FAILED' | 'CONTEXT_DENIED' | 'UPSTREAM_RUNTIME_BAD_REQUEST' | 'UPSTREAM_RUNTIME_AUTH_ERROR' | 'UPSTREAM_RUNTIME_NOT_FOUND' | 'UPSTREAM_RUNTIME_VALIDATION_ERROR' | 'UPSTREAM_RUNTIME_RATE_LIMIT' | 'UPSTREAM_RUNTIME_SERVER_ERROR' | 'UPSTREAM_RUNTIME_UNMAPPED' | 'NETWORK_TRANSPORT_RUNTIME_TIMEOUT' | 'NETWORK_TRANSPORT_RUNTIME_UNREACHABLE' | 'NETWORK_TRANSPORT_RUNTIME_UNMAPPED' | 'UNKNOWN', required
      - `message` string, required
      - `retry_after_ms` integer
      - `stacktrace` string
      - `status_code` integer
    - `logs` ToolLog[]
      - `level` string, required
      - `message` string, required
      - `subtype` string
    - `value` unknown
  - `run_at` string
  - `status` string
  - `success` boolean — Whether the request was successful. For immediately-executed requests, this will be true if the tool call succeeded. For scheduled requests, this will be true if the request was scheduled successfully.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `415` — Unsupported Media Type
- `500` — Internal Server Error

## Changes

- **2026-04-16** `a509111298b2` — 3 warning
  - added the new `NETWORK_TRANSPORT_RUNTIME_TIMEOUT` enum value to the `output/error/kind` response property for the response status `200`
  - added the new `NETWORK_TRANSPORT_RUNTIME_UNMAPPED` enum value to the `output/error/kind` response property for the response status `200`
  - added the new `NETWORK_TRANSPORT_RUNTIME_UNREACHABLE` enum value to the `output/error/kind` response property for the response status `200`
- **2026-01-22** `0df52128804d` — 2 warning
  - added the new `CONTEXT_CHECK_FAILED` enum value to the `output/error/kind` response property for the response status `200`
  - added the new `CONTEXT_DENIED` enum value to the `output/error/kind` response property for the response status `200`
- **2025-10-30** `f59a2fe653b8` — 1 warning
  - deleted the `header` request parameter `Authorization`

[Change history](https://skmtc.dev/arcadeai/apis/arcade-api/changes/v1/tools/execute/post.md)

---

[API](https://skmtc.dev/arcadeai/apis/arcade-api.md) · [All operations](https://skmtc.dev/arcadeai/apis/arcade-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/arcadeai/arcade-api/revisions/a509111298b2/schema)