Execute a tool

POST/api/v1/execute_tool

Runs one tool as a user, with that user's credentials for the connection. Identify the account with connector and identifier, or with connected_account_id, and pass the tool's inputs in params; each connector page lists its tools and their inputs. When the connected account is EXPIRED, the call returns 401 with TOOL_ERROR; when it's otherwise not ACTIVE, 400 with INVALID_ARGUMENT. Either way, send the user an authorization link. Errors and rate limits explains each tool error code.

This page as markdown Tools overview

Authorization

Authorization: Bearer $TOKEN, an access token from the client credentials grant. See Authentication.

Body

tool_namestringrequired

Name of the tool to execute

agent_run_idstring

Customer-supplied identifier grouping multiple tool calls into a single agent run. Useful for correlating logs across an agentic workflow.

connected_account_idstring

The unique ID of the connected account. Use this to directly identify the connected account instead of using identifier + connector combination.

connectorstring

The connection name, as shown in AgentKit > Connections.

identifierstring

Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address.

organization_idstring

The organization ID to scope the connected account lookup. Use this to narrow down the search when the same identifier exists across multiple organizations.

paramsobject

JSON object containing the parameters required for tool execution. The structure depends on the specific tool being executed.

user_idstring

The user ID to scope the connected account lookup. Use this to narrow down the search when the same identifier exists across multiple users.

scalekit_client.actions.execute_tool

Execute a tool with the given parameters.

scalekit_client.actions.execute_tool(
    tool_input: ToolInput,
    tool_name: str,
    identifier: Optional[str] = None,
    tool_request: Optional[ToolRequest] = None,
    connected_account_id: Optional[str] = None,
    connection_name: Optional[str] = None,
) -> ExecuteToolResponse

Parameters

tool_inputToolInputrequired

Input data for the tool execution

tool_namestrrequired

Name of the tool to execute

identifierOptional[str]

Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address.

connected_account_idOptional[str]

ID of the connected account to use. Provide this OR the (identifier + connection_name) pair — not both.

connection_nameOptional[str]

The connection name, as shown in AgentKit > Connections.

Returns ExecuteToolResponse: The tool's output in data, and the execution_id.

From scalekit-sdk-python 2.19.1.

scalekit.actions.executeTool

Execute a tool on behalf of a connected account. Identify the account with connector and identifier, or with connectedAccountId.

scalekit.actions.executeTool(
  params: {
    toolName: string;
    toolInput: Record<string, unknown>;
    identifier?: string;
    connectedAccountId?: string;
    connector?: string;
    organizationId?: string;
    userId?: string;
  },
): Promise<ExecuteToolResponse>

Parameters

toolNamestringrequired

Name of the tool to execute

toolInputRecord<string, unknown>required

JSON object containing the parameters required for tool execution. The structure depends on the specific tool being executed.

identifierstring

Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address.

connectedAccountIdstring

The unique ID of the connected account. Use this to directly identify the connected account instead of using identifier + connector combination.

connectorstring

The connection name, as shown in AgentKit > Connections.

organizationIdstring

The organization ID to scope the connected account lookup. Use this to narrow down the search when the same identifier exists across multiple organizations.

userIdstring

The user ID to scope the connected account lookup. Use this to narrow down the search when the same identifier exists across multiple users.

Returns Promise<ExecuteToolResponse>.

From @scalekit-sdk/node 2.18.0.

Response 200

dataobject

The tool's output: the app's response, as JSON.

execution_idstring

Unique identifier for the tool execution

Errors

Every error has the same body: code, message and details. See Errors and rate limits.

400Invalid request - error code INVALID_ARGUMENT when the tool name is missing, the input doesn't match the tool's schema, the connected account belongs to a different app than the tool, or the account isn't ACTIVE. Error code TOOL_ERROR when the app rejected the call; tool_error_info.tool_error_code is INVALID_ARGUMENT, EXECUTION_ERROR, INTERNAL_ERROR or, for a tool from an app's MCP server, TOOL_ERROR, and tool_error_message has the app's message.

401Error code UNAUTHENTICATED when your access token is missing, invalid or expired; get a new token and retry. Error code TOOL_ERROR with tool_error_code REAUTHENTICATION_NEEDED or UNAUTHENTICATED when the user's access to the app was revoked or expired; send the user a new authorization link.

403Error code TOOL_ERROR with tool_error_code FORBIDDEN or PERMISSION_DENIED - the app refused the call. The account's credentials are valid but lack the scope this tool needs. The connected account stays ACTIVE; grant the missing scope on the connection, have the user authorize again, then retry.

404Not found - the tool or the connected account doesn't exist. Error code TOOL_ERROR with tool_error_code RESOURCE_NOT_FOUND when the app couldn't find what the call refers to, such as an event ID.

429Error code TOOL_ERROR with tool_error_code RATE_LIMITED - the app rate-limited the call. Back off and retry.

500Error code TOOL_ERROR with tool_error_code INTERNAL_ERROR when Scalekit couldn't run the tool, for example because the connection's auth type isn't supported for this tool. For a tool from an app's MCP server, tool_error_code TOOL_ERROR when that server failed, rate-limited the call or couldn't be reached; its status is in tool_error_message. A retry can run the tool twice, so retry only tools that are safe to repeat, and quote execution_id to support.

Used in

Every connector page shows this call with that connector's tools and their inputs.

Request

curl -sS -X POST \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/execute_tool" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "gmail_fetch_mails",
    "connector": "gmail",
    "identifier": "user_123",
    "params": {
      "query": "is:unread",
      "max_results": 5
    }
  }'

result = scalekit_client.actions.execute_tool(
    tool_input={"query": "is:unread", "max_results": 5},
    tool_name="gmail_fetch_mails",
    identifier="user_123",
    connection_name="gmail",
)

const result = await scalekit.actions.executeTool({
  toolName: "gmail_fetch_mails",
  toolInput: { query: "is:unread", max_results: 5 },
  identifier: "user_123",
  connector: "gmail",
});

Response 200

1
{
2
  "data": {
3
    "messages": [
4
      {
5
        "id": "19a4f2c8e6b1d037",
6
        "threadId": "19a4f2c8e6b1d037",
7
        "labelIds": [
8
          "UNREAD",
9
          "IMPORTANT",
10
          "INBOX"
11
        ],
12
        "snippet": "Here are the notes from today's planning call",
13
        "payload": {
14
          "mimeType": "multipart/alternative",
15
          "headers": [
16
            {
17
              "name": "From",
18
              "value": "Dana Lee <dana@example.com>"
19
            },
20
            {
21
              "name": "Subject",
22
              "value": "Notes from the planning call"
23
            },
24
            {
25
              "name": "Date",
26
              "value": "Fri, 2 Oct 2026 13:52:10 +0000"
27
            }
28
          ]
29
        },
30
        "sizeEstimate": 6421,
31
        "historyId": "2174983",
32
        "internalDate": "1790949130000"
33
      }
34
    ],
35
    "page_token": ""
36
  },
37
  "execution_id": "6f1c2e4a-a0b3-11f1-9c2a-0242ac120002"
38
}