# Execute a tool within a tool router session

**Documentation:** /reference/api-reference/tool-router/postToolRouterSessionBySessionIdExecute

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

---

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

**Endpoint:** `https://backend.composio.dev/api/v3.1/tool_router/session/{session_id}/execute`

**Summary:** Execute a tool within a tool router session

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

### Authentication

**ApiKeyAuth** - API Key in `header` header `x-api-key` OR **UserApiKeyAuth** - API Key in `header` header `x-user-api-key`

### Path Parameters

- `session_id` (string (toolRouterSessionId)) *(required)*: Tool router session ID (required for public API, optional for internal - injected by middleware)

### Request Body

**Schema:**

- `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
  - `[key: string]` (any)
- `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` (array<object>): Custom toolkits with grouped tools. Toolkit slugs must not conflict with existing Composio toolkits. All tools are no-auth.
    - Array items:
      - `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` (array<object>) *(required)*: Tools in this custom toolkit
        - Array items:
          - ...
  - `custom_tools` (array<object>): Custom tools to include in search. Standalone tools need no auth. Tools with extends_toolkit inherit the Composio toolkit's connection.
    - Array items:
      - `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.
        - `[key: string]` (any)
      - `output_schema` (object): JSON Schema describing tool output (optional)
        - `[key: string]` (any)
      - `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.

**Example:**

```json
{
  "tool_slug": "string",
  "arguments": {},
  "account": "string",
  "enable_auto_workbench_offload": true,
  "experimental": {
    "custom_toolkits": [
      {
        "slug": "...",
        "name": "...",
        "description": "...",
        "preload": "...",
        "tools": "..."
      }
    ],
    "custom_tools": [
      {
        "slug": "...",
        "name": "...",
        "description": "...",
        "input_schema": "...",
        "output_schema": "...",
        "extends_toolkit": "...",
        "preload": "..."
      }
    ]
  }
}
```

### Responses

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

**Response Schema:**

- `data` (object) *(required)*: The data returned by the tool execution
  - `[key: string]` (any)
- `error` (string,null) *(required)*: Error message if the execution failed, null otherwise
- `log_id` (string) *(required)*: Unique identifier for the execution log

**Example Response:**

```json
{
  "data": {
    "key": null
  },
  "error": null,
  "log_id": "string"
}
```

#### 400 - Bad request

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 401 - Unauthorized

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 403 - Forbidden

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 404 - Not found

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 413 - Payload too large

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 429 - Too many requests

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 500 - Internal server error

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 502 - Bad gateway

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

### Example cURL Request

```bash
curl -X POST "https://backend.composio.dev/api/v3.1/tool_router/session/string/execute" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_slug": "string",
    "arguments": {},
    "account": "string",
    "enable_auto_workbench_offload": true,
    "experimental": {
      "custom_toolkits": [
        {
          "slug": "...",
          "name": "...",
          "description": "...",
          "preload": "...",
          "tools": "..."
        }
      ],
      "custom_tools": [
        {
          "slug": "...",
          "name": "...",
          "description": "...",
          "input_schema": "...",
          "output_schema": "...",
          "extends_toolkit": "...",
          "preload": "..."
        }
      ]
    }
  }'
```