---
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
- `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

---

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