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

# Execute Tool

`POST /v1/tools/execute`

Executes a tool by name and arguments

## Headers

- `Authorization` string, required

## 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' | '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' | '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

---

[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/8446c4e394ac/schema)