---
title: "Execute a tool within a tool router session"
method: POST
path: "/api/v3.1/tool_router/session/{session_id}/execute"
tags: ["Tool Router"]
---

# Execute a tool within a tool router session

`POST /api/v3.1/tool_router/session/{session_id}/execute`

Execute a tool (meta or app) within an existing tool router session.

## Path parameters

- `session_id` string, toolRouterSessionId — The unique identifier of the tool router session. Required for public API endpoints, optional for internal endpoints where it is injected by middleware.

## Request body

- object
  - `tool_slug` string, required — The unique slug identifier of the tool to execute. Supports both meta tools and app tools exposed by the session.
  - `arguments` object — The arguments required by the tool
  - `account` string — Account identifier to specify which connected account to use for direct tool execution. Use the account ID (e.g. "coup_hurricane_dal_analytical") or an alias. When omitted with a single account, the default is used. When omitted with multiple accounts, an error lists available accounts. Meta/helper tools either ignore this top-level field or define their own account-selection fields, for example COMPOSIO_MULTI_EXECUTE_TOOL.tools[].account.
  - `enable_auto_workbench_offload` boolean — When true, direct non-meta tool execution may return a workbench offload preview if the response exceeds the configured threshold and the session workbench is enabled. When omitted or false, direct tool execution returns the normal inline response. Meta/helper tools are unaffected, and COMPOSIO_MULTI_EXECUTE_TOOL uses session.workbench configuration for its own batch-level offload behavior.
  - `experimental` object — Inline custom tools and toolkits for this request. v3.1 sessions do not persist customs — pass them on every request that needs them.
    - `custom_toolkits` object[] — Custom toolkits with grouped tools. Toolkit slugs must not conflict with existing Composio toolkits. All tools are no-auth.
      - `slug` string, required — Unique slug for the toolkit. Must not conflict with existing Composio toolkit slugs. Alphanumeric, underscores, and hyphens only.
      - `name` string, required — Display name shown to the LLM and in search results.
      - `description` string, required — Used for BM25 search matching and shown in toolkit connection statuses.
      - `preload` boolean — SDK hint for direct custom-tool exposure. Not stored in session config; echoed in create/attach responses for inline custom definitions.
      - `tools` object[], required — Tools in this custom toolkit
        - `slug` string, required — Tool slug. Combined with toolkit slug to form LOCAL_<TOOLKIT>_<TOOL> (max 60 chars total).
        - `name` string, required — Human-readable display name
        - `description` string, required — Used for BM25 search matching and shown to the LLM.
        - `input_schema` object, required — Must have type: "object" and a properties field.
        - `output_schema` object — Optional output schema for the tool response.
        - `preload` boolean — SDK hint for direct custom-tool exposure. Not stored in session config; echoed in create/attach responses for inline custom definitions.
    - `custom_tools` object[] — Custom tools to include in search. Standalone tools need no auth. Tools with extends_toolkit inherit the Composio toolkit's connection.
      - `slug` string, required — Tool slug. Forms LOCAL_<TOOL> (standalone) or LOCAL_<TOOLKIT>_<TOOL> (extending). Max 60 chars total.
      - `name` string, required — Human-readable display name
      - `description` string, required — Used for BM25 search matching and shown to the LLM.
      - `input_schema` object, required — Must have type: "object" and a properties field.
      - `output_schema` object — JSON Schema describing tool output (optional)
      - `extends_toolkit` string — If set, must be a valid Composio toolkit slug. The tool inherits that toolkit's auth/connection status. If omitted, the tool is standalone (no-auth).
      - `preload` boolean — SDK hint for direct custom-tool exposure. Not stored in session config; echoed in create/attach responses for inline custom definitions.

## Response `200`

Successfully executed the tool. Returns execution result, logs, and status.

- object
  - `data` object, required — The data returned by the tool execution
  - `error` string, nullable, required — Error message if the execution failed, null otherwise
  - `log_id` string, required — Unique identifier for the execution log

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not found
- `413` — Payload too large
- `429` — Too many requests
- `500` — Internal server error
- `502` — Bad gateway

---

[API](https://skmtc.net/composiohq/apis/composio-platform-api-v3-1.md) · [All operations](https://skmtc.net/composiohq/apis/composio-platform-api-v3-1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/composiohq/composio-platform-api-v3-1/versions/4239836857f8/schema)