---
title: "Execute a tool using a connected account"
method: POST
path: "/api/v1/execute_tool"
tags: ["Tool Calling"]
---

# Execute a tool using a connected account

`POST /api/v1/execute_tool`

Executes a tool action using authentication credentials from a connected account. Specify the tool by name and provide required parameters as JSON. The connected account can be identified by ID, or by combination of organization/user, connector, and identifier. Returns the execution result data and a unique execution ID for tracking. Use this endpoint to perform actions like sending emails, creating calendar events, or managing resources in external services.

## Request body

- ToolsExecuteToolRequest
  - `agent_run_id` string — Optional. Customer-supplied identifier grouping multiple tool calls into a single agent run. Useful for correlating logs across an agentic workflow.
  - `connected_account_id` string — Optional. The unique ID of the connected account. Use this to directly identify the connected account instead of using identifier + connector combination.
  - `connector` string — Optional. The name of the connector/provider (e.g., 'Google Workspace', 'Slack', 'Notion'). Alphanumeric characters, spaces, hyphens, underscores, and colons are allowed. Use this in combination with identifier to identify the connected account.
  - `identifier` string — Optional. The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). Use this in combination with connector to identify the connected account.
  - `organization_id` string — Optional. The organization ID to scope the connected account lookup. Use this to narrow down the search when the same identifier exists across multiple organizations.
  - `params` object — JSON object containing the parameters required for tool execution. The structure depends on the specific tool being executed.
  - `tool_name` string — Name of the tool to execute
  - `user_id` string — Optional. The user ID to scope the connected account lookup. Use this to narrow down the search when the same identifier exists across multiple users.

## Response `200`

Tool executed successfully with result data and execution ID

- ToolsExecuteToolResponse
  - `data` object — Free-flowing JSON parameters for the tool execution
  - `execution_id` string — Unique identifier for the tool execution

## Other responses

- `400` — Invalid request - occurs when tool name is missing, parameters are malformed, or tool definition validation fails
- `401` — Authentication required - missing or invalid access token
- `403` — Insufficient permission - the connected account's credentials are valid but lack the scope required for this tool. The connected account stays ACTIVE; no reconnection is required. Grant the missing scope for this tool's provider, then retry.
- `404` — Tool or connected account not found - occurs when the specified tool name or connected account does not exist
- `500` — Tool execution failed - occurs when the external service returns an error or the tool encounters a runtime exception

## Changes

- **2026-08-31** `49af6b0b79c6` — 1 info
  - added the non-success response with the status `403`

[Change history](https://skmtc.dev/scalekit/apis/scalekit-api-reference/changes/api/v1/execute_tool/post.md)

---

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