# Get a tool router session by ID

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

Retrieves an existing tool router session by its ID. Returns the session configuration, MCP server URL, and available tools.

---

## GET `/api/v3/tool_router/session/{session_id}`

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

**Summary:** Get a tool router session by ID

Retrieves an existing tool router session by its ID. Returns the session configuration, MCP server URL, and available tools.

### 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)*: The unique identifier of the tool router session

### Responses

#### 200 - Session successfully retrieved. Returns the session details including configuration.

**Response Schema:**

- `session_id` (string (toolRouterSessionId)) *(required)*: The identifier of the session
- `mcp` (object) *(required)*
  - `type` (enum: "http") *(required)*: The type of the MCP server. Can be http
  - `url` (string (uri)) *(required)*: The URL of the MCP server
- `tool_router_tools` (array<string>) *(required)*: List of available tools in this session
- `config` (object) *(required)*: The session configuration including user, toolkits, and overrides
  - `user_id` (string) *(required)*: User identifier for this session
  - `toolkits` (any): Toolkit configuration - either enabled list or disabled list
  - `auth_configs` (object): Auth config overrides per toolkit
    - `[key: string]` (string (authConfigId))
  - `connected_accounts` (object): Connected account overrides per toolkit
    - `[key: string]` (string (connectedAccountId))
  - `manage_connections` (object): Manage connections configuration
    - `enabled` (boolean): Whether to enable the connection manager for automatic connection handling
    - `callback_url` (string (uri)): Custom callback URL for connected account auth flows
    - `enable_wait_for_connections` (boolean): Enable the COMPOSIO_WAIT_FOR_CONNECTIONS tool for polling connection status. Default false. May not work reliably with GPT models.
  - `tools` (object): Tool-level configuration per toolkit
    - `[key: string]` (any)
  - `tags` (object): MCP tool annotation hints for filtering tools with enabled/disabled support. enabled: tags that the tool must have at least one of. disabled: tags that the tool must NOT have any of. Both conditions must be satisfied.
    - `enabled` (array<enum: "readOnlyHint" | "destructiveHint" | "idempotentHint" | ...>): Tags that the tool must have at least one of
    - `disabled` (array<enum: "readOnlyHint" | "destructiveHint" | "idempotentHint" | ...>): Tags that the tool must NOT have any of
  - `workbench` (object): Workbench configuration
    - `enable` (boolean): Whether the workbench (code execution sandbox) is enabled. When false, COMPOSIO_REMOTE_WORKBENCH and COMPOSIO_REMOTE_BASH_TOOL are not exposed.
    - `proxy_execution_enabled` (boolean): Whether proxy execution is enabled in the workbench
    - `auto_offload_threshold` (number): Character threshold after which tool execution response are saved to a file in workbench. Default is 20k.
- `experimental` (object): Experimental features
  - `assistive_prompt` (string): The assistive system prompt for the tool router session
  - `custom_toolkits` (array<object>): User-defined custom toolkits with grouped tools (no-auth)
    - Array items:
      - `slug` (string) *(required)*
      - `name` (string) *(required)*
      - `description` (string) *(required)*
      - `tools` (array<object>) *(required)*
        - Array items:
          - ...
  - `custom_tools` (array<object>): Custom tools — standalone or extending Composio toolkits
    - Array items:
      - `slug` (string) *(required)*: Prefixed tool slug (e.g. LOCAL_GMAIL_GET_IMPORTANT_EMAILS)
      - `name` (string) *(required)*
      - `description` (string) *(required)*
      - `input_schema` (object) *(required)*
        - `[key: string]` (any)
      - `output_schema` (object)
        - `[key: string]` (any)
      - `extends_toolkit` (string)
      - `original_slug` (string) *(required)*: Original tool slug as provided by the user

**Example Response:**

```json
{
  "session_id": "string",
  "mcp": {
    "type": "http",
    "url": "https://example.com"
  },
  "tool_router_tools": [
    "string"
  ],
  "config": {
    "user_id": "string",
    "toolkits": null,
    "auth_configs": {
      "key": "string"
    },
    "connected_accounts": {
      "key": "string"
    },
    "manage_connections": {
      "enabled": true,
      "callback_url": "https://example.com",
      "enable_wait_for_connections": false
    },
    "tools": {
      "key": null
    },
    "tags": {
      "enabled": [
        "..."
      ],
      "disabled": [
        "..."
      ]
    },
    "workbench": {
      "enable": true,
      "proxy_execution_enabled": true
    }
  },
  "experimental": {
    "assistive_prompt": "string",
    "custom_toolkits": [
      {
        "slug": "...",
        "name": "...",
        "description": "...",
        "tools": "..."
      }
    ],
    "custom_tools": [
      {
        "slug": "...",
        "name": "...",
        "description": "...",
        "input_schema": "...",
        "output_schema": "...",
        "extends_toolkit": "...",
        "original_slug": "..."
      }
    ]
  }
}
```

#### 400 - Bad request. This may occur if the session_id format is invalid, please pass this in trs_ prefix format

**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. Authentication is required or the provided credentials are invalid.

**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. The session with the provided ID does not exist or has been deleted.

**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. An unexpected error occurred while processing the 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>)

### Example cURL Request

```bash
curl -X GET "https://backend.composio.dev/api/v3/tool_router/session/string" \
  -H "x-api-key: YOUR_API_KEY"
```