> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a tool router session by ID (v3.1)

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



## OpenAPI

````yaml api-reference/openapi.json GET /api/v3.1/tool_router/session/{session_id}
openapi: 3.1.0
info:
  version: 3.1.0
  title: Composio Platform API v3.1
  description: >-
    Composio v3.1 API — all endpoints available under /api/v3.1/. Tool endpoints
    default to the latest tool version.
  contact:
    name: Composio Support
    url: https://composio.dev/support
    email: support@composio.dev
  license:
    name: Proprietary
    url: https://composio.dev/terms
servers:
  - url: https://backend.composio.dev
    description: Composio production API
security:
  - ApiKeyAuth: []
tags:
  - name: Authentication
    description: Authentication related endpoints
    x-group: Authentication
  - name: Auth Configs
    description: Authentication configuration management
    x-group: Auth Configs
  - name: Connected Accounts
    description: Connected account management
    x-group: Connected Accounts
  - name: Logs
    description: Logging and monitoring
    x-group: Logs
  - name: OpenAPI
    description: OpenAPI specification management
    x-group: OpenAPI
  - name: Organization
    description: Organization management
    x-group: Organization
  - name: API Keys
    description: API key management
    x-group: API Keys
  - name: Webhooks
    description: Webhook configuration
    x-group: Webhooks
  - name: Webhook Endpoints
    description: >-
      Per-OAuth-app webhook ingress endpoints. Inbound URLs the provider posts
      to, plus signing secret storage and verification.
    x-group: Webhook Endpoints
  - name: Webhook Subscriptions
    description: >-
      Webhook delivery subscriptions. Outbound URLs Composio posts trigger
      events to, plus signing secret rotation and event-type filters.
    x-group: Webhook Subscriptions
  - name: Team
    description: Team member management
    x-group: Team
  - name: Consumer Skills
    description: Organization-authored Skill management
    x-group: Consumer Skills
  - name: Toolkits
    description: Toolkit and tool management
    x-group: Toolkits
  - name: Tools
    description: Tool execution endpoints
    x-group: Tools
  - name: Triggers
    description: Trigger management and execution
    x-group: Triggers
  - name: Payments
    description: Payment and subscription management
    x-group: Payments
  - name: Billing
    description: Dashboard billing state — usage, subscription, contract (cookie-auth only)
    x-group: Billing
  - name: Compliance
    description: Organization compliance agreements and acceptance state
    x-group: Compliance
  - name: Files
    description: File management
    x-group: Files
  - name: MCP
    description: MCP server management
    x-group: MCP
  - name: MCP Partner
    description: MCP partner management
    x-group: MCP Partner
  - name: Stripe Projects
    description: Stripe Projects provisioning
    x-group: Stripe Projects
  - name: Tool Router
    description: (Labs) Tool router endpoints
    x-group: Sessions (Prev Tool Router)
  - name: Playground
    description: Dashboard playground chat
    x-group: Playground
  - name: Arena
    description: Arena conversations, messages and terms
    x-group: Arena
  - name: Projects
    description: Projects API endpoints.
    x-group: Projects
  - name: Organization Management
    description: Organization Management API endpoints.
    x-group: Organization Management
  - name: Webhook Events
    description: Events delivered by Composio to your registered webhook endpoints
    x-group: Webhook Events
paths:
  /api/v3.1/tool_router/session/{session_id}:
    get:
      tags:
        - Tool Router
      summary: Get a tool router session by ID (v3.1)
      description: >-
        Retrieves an existing tool router session by its ID. Returns the session
        configuration, MCP server URL, and available tools.
      operationId: getToolRouterSessionBySessionId
      parameters:
        - schema:
            type: string
            format: toolRouterSessionId
            description: The session ID returned when creating the session
            example: trs_1a2b3c4d5e6f
          required: true
          description: The unique identifier of the tool router session
          name: session_id
          in: path
      responses:
        '200':
          description: >-
            Session successfully retrieved. Returns the session details
            including configuration.
          content:
            application/json:
              schema:
                type: object
                properties:
                  session_id:
                    type: string
                    format: toolRouterSessionId
                    description: The identifier of the session
                    example: trs_1a2b3c4d5e6f
                  mcp:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - http
                        description: The type of the MCP server. Can be http
                      url:
                        type: string
                        format: uri
                        description: The URL of the MCP server
                        example: >-
                          https://app.composio.dev/tool_router/v3/trs_1a2b3c4d5e6f/mcp
                    required:
                      - type
                      - url
                  tool_router_tools:
                    type: array
                    items:
                      type: string
                    description: List of available tools in this session
                  config:
                    type: object
                    properties:
                      user_id:
                        type: string
                        description: User identifier for this session
                      toolkits:
                        anyOf:
                          - type: object
                            properties:
                              enabled:
                                type: array
                                items:
                                  type: string
                              require_approval:
                                type: array
                                items:
                                  type: string
                                description: >-
                                  Tool calls matched here pause until the user
                                  approves them.
                                x-experimental: true
                            required:
                              - enabled
                            additionalProperties: false
                          - type: object
                            properties:
                              disabled:
                                type: array
                                items:
                                  type: string
                              require_approval:
                                type: array
                                items:
                                  type: string
                                description: >-
                                  Tool calls matched here pause until the user
                                  approves them.
                                x-experimental: true
                            required:
                              - disabled
                            additionalProperties: false
                          - type: object
                            properties:
                              require_approval:
                                type: array
                                items:
                                  type: string
                                description: >-
                                  Tool calls matched here pause until the user
                                  approves them.
                                x-experimental: true
                            required:
                              - require_approval
                            additionalProperties: false
                        description: >-
                          Toolkit configuration - either enabled list or
                          disabled list, or toolkits whose tools need approval
                      auth_configs:
                        type: object
                        additionalProperties:
                          type: string
                          format: authConfigId
                        description: Auth config overrides per toolkit
                      instant:
                        anyOf:
                          - type: boolean
                            enum:
                              - false
                          - type: object
                            properties:
                              toolkits:
                                anyOf:
                                  - type: object
                                    properties:
                                      enabled:
                                        type: array
                                        items:
                                          type: string
                                    required:
                                      - enabled
                                    additionalProperties: false
                                  - type: object
                                    properties:
                                      disabled:
                                        type: array
                                        items:
                                          type: string
                                    required:
                                      - disabled
                                    additionalProperties: false
                                description: >-
                                  Toolkits eligible for instant usage, as an
                                  enabled or disabled list. If absent, no
                                  additional toolkit restriction applies.
                              tools:
                                type: object
                                additionalProperties:
                                  anyOf:
                                    - type: object
                                      properties:
                                        enabled:
                                          type: array
                                          items:
                                            type: string
                                      required:
                                        - enabled
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        disabled:
                                          type: array
                                          items:
                                            type: string
                                      required:
                                        - disabled
                                      additionalProperties: false
                                description: >-
                                  Per-toolkit enabled or disabled lists that
                                  restrict instant usage. Toolkits absent from
                                  this map have no additional tool restriction.
                              return_instant_charge:
                                type: boolean
                                description: >-
                                  Whether session tool responses return a
                                  top-level instant_charge when a charge is
                                  available. Defaults to false; controls
                                  response visibility only.
                              return_prices_in_search:
                                type: boolean
                                description: >-
                                  Experimental. Whether tool search results show
                                  each instant tool's price, under
                                  instant_account.prices. Defaults to false.
                                x-experimental: true
                            required:
                              - return_instant_charge
                              - return_prices_in_search
                            additionalProperties: false
                        description: >-
                          Instant usage settings. False disables instant usage;
                          an object permits it subject to project permission and
                          session toolkit and tool restrictions.
                      manage_connections:
                        type: object
                        properties:
                          enabled:
                            type: boolean
                            default: true
                            description: >-
                              Whether to enable the connection manager for
                              automatic connection handling
                          callback_url:
                            type: string
                            format: uri
                            description: >-
                              Custom callback URL for connected account auth
                              flows
                          enable_wait_for_connections:
                            type: boolean
                            default: false
                            description: >-
                              Enable the COMPOSIO_WAIT_FOR_CONNECTIONS tool for
                              polling connection status. Default false. May not
                              work reliably with GPT models.
                          enable_connection_removal:
                            type: boolean
                            default: true
                            description: >-
                              Enable the "remove" action in
                              COMPOSIO_MANAGE_CONNECTIONS. Default true.
                        description: Manage connections configuration
                      tools:
                        type: object
                        additionalProperties:
                          anyOf:
                            - type: object
                              properties:
                                enabled:
                                  type: array
                                  items:
                                    type: string
                                require_approval:
                                  type: array
                                  items:
                                    type: string
                                  description: >-
                                    Tool calls matched here pause until the user
                                    approves them.
                                  x-experimental: true
                              required:
                                - enabled
                              additionalProperties: false
                            - type: object
                              properties:
                                disabled:
                                  type: array
                                  items:
                                    type: string
                                require_approval:
                                  type: array
                                  items:
                                    type: string
                                  description: >-
                                    Tool calls matched here pause until the user
                                    approves them.
                                  x-experimental: true
                              required:
                                - disabled
                              additionalProperties: false
                            - type: object
                              properties:
                                tags:
                                  type: object
                                  properties:
                                    enabled:
                                      type: array
                                      items:
                                        type: string
                                        enum:
                                          - readOnlyHint
                                          - createHint
                                          - updateHint
                                          - destructiveHint
                                          - idempotentHint
                                          - openWorldHint
                                      description: >-
                                        Tags that the tool must have at least
                                        one of
                                    disabled:
                                      type: array
                                      items:
                                        type: string
                                        enum:
                                          - readOnlyHint
                                          - createHint
                                          - updateHint
                                          - destructiveHint
                                          - idempotentHint
                                          - openWorldHint
                                      description: Tags that the tool must NOT have any of
                                    require_approval:
                                      type: array
                                      items:
                                        type: string
                                        enum:
                                          - readOnlyHint
                                          - createHint
                                          - updateHint
                                          - destructiveHint
                                          - idempotentHint
                                          - openWorldHint
                                      description: >-
                                        Tool calls matched here pause until the
                                        user approves them.
                                      x-experimental: true
                                require_approval:
                                  type: array
                                  items:
                                    type: string
                                  description: >-
                                    Tool calls matched here pause until the user
                                    approves them.
                                  x-experimental: true
                              required:
                                - tags
                              additionalProperties: false
                            - type: object
                              properties:
                                require_approval:
                                  type: array
                                  items:
                                    type: string
                                  description: >-
                                    Tool calls matched here pause until the user
                                    approves them.
                                  x-experimental: true
                              required:
                                - require_approval
                              additionalProperties: false
                        description: >-
                          Tool-level configuration per toolkit: tools to enable
                          or disable, or tools that need approval
                      tags:
                        type: object
                        properties:
                          enabled:
                            type: array
                            items:
                              type: string
                              enum:
                                - readOnlyHint
                                - createHint
                                - updateHint
                                - destructiveHint
                                - idempotentHint
                                - openWorldHint
                            description: Tags that the tool must have at least one of
                          disabled:
                            type: array
                            items:
                              type: string
                              enum:
                                - readOnlyHint
                                - createHint
                                - updateHint
                                - destructiveHint
                                - idempotentHint
                                - openWorldHint
                            description: Tags that the tool must NOT have any of
                          require_approval:
                            type: array
                            items:
                              type: string
                              enum:
                                - readOnlyHint
                                - createHint
                                - updateHint
                                - destructiveHint
                                - idempotentHint
                                - openWorldHint
                            description: >-
                              Tool calls matched here pause until the user
                              approves them.
                            x-experimental: true
                        description: >-
                          MCP tool annotation hints for filtering tools with
                          enabled/disabled support, and experimentally the tags
                          whose tools need approval. 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.
                      workbench:
                        type: object
                        properties:
                          enable:
                            type: boolean
                            description: >-
                              Whether the workbench (code execution sandbox) is
                              enabled. When false, COMPOSIO_REMOTE_WORKBENCH and
                              COMPOSIO_REMOTE_BASH_TOOL are not exposed.
                          tool_execution_enabled:
                            type: boolean
                            description: Whether tool execution is enabled in the workbench
                          proxy_execution_enabled:
                            type: boolean
                            description: >-
                              Whether proxy execution is enabled in the
                              workbench
                          auto_offload_threshold:
                            type: number
                            description: >-
                              Character threshold after which tool execution
                              response are saved to a file in workbench. Default
                              is 20k.
                            exclusiveMinimum: 0
                          sandbox_size:
                            type: string
                            enum:
                              - standard
                              - medium
                              - large
                              - xlarge
                            description: >-
                              Sandbox compute tier: standard (1 vCPU / 1 GB),
                              medium (2 vCPU / 2 GB), large (4 vCPU / 4 GB),
                              xlarge (8 vCPU / 8 GB). Defaults to standard.
                        default:
                          enable: true
                          proxy_execution_enabled: true
                        description: Workbench configuration
                      multi_account:
                        type: object
                        properties:
                          enable:
                            type: boolean
                            description: >-
                              When true, enables multi-account mode for this
                              session. When not set, falls back to
                              org/project-level configuration.
                          max_accounts_per_toolkit:
                            type: integer
                            description: >-
                              Maximum number of connected accounts allowed per
                              toolkit. Defaults to 5 when multi-account is
                              enabled.
                          require_explicit_selection:
                            type: boolean
                            description: >-
                              When true, require explicit account selection when
                              multiple accounts are connected. When false
                              (default), use the first/default account.
                        description: Multi-account configuration for this session.
                      proxy_execute:
                        type: object
                        properties:
                          enable:
                            type: boolean
                            description: >-
                              When true, enables proxy execute outside the
                              workbench. When false, also disables proxy
                              execution inside the workbench.
                        required:
                          - enable
                        description: >-
                          Proxy execute configuration for this session. Omitted
                          when not set.
                      hooks:
                        type: array
                        items:
                          oneOf:
                            - type: object
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - before_execute
                                id:
                                  type: string
                                  pattern: ^[a-z0-9_-]{1,64}$
                                  description: >-
                                    Unique within the session. Shows up in
                                    results and logs.
                                name:
                                  type: string
                                  minLength: 1
                                  maxLength: 120
                                  description: >-
                                    A readable name. The agent sees it when this
                                    hook blocks a call.
                                applies_to:
                                  anyOf:
                                    - type: string
                                      enum:
                                        - all
                                    - type: object
                                      properties:
                                        toolkits:
                                          type: array
                                          items:
                                            type: string
                                            minLength: 1
                                          minItems: 1
                                          description: Toolkit slugs
                                      required:
                                        - toolkits
                                      additionalProperties: false
                                  description: >-
                                    Which tools the hook covers: "all" for all
                                    of them, or only the listed toolkits.
                                handler:
                                  type: object
                                  properties:
                                    type:
                                      type: string
                                      enum:
                                        - condition_check
                                    condition:
                                      type: string
                                      minLength: 1
                                      maxLength: 2000
                                      description: >-
                                        What to block, written as a plain
                                        sentence. For example: "Sending email to
                                        anyone outside example.org".
                                    action:
                                      type: string
                                      enum:
                                        - block
                                  required:
                                    - type
                                    - condition
                                    - action
                                  additionalProperties: false
                              required:
                                - type
                                - id
                                - applies_to
                                - handler
                              additionalProperties: false
                            - type: object
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - after_execute
                                id:
                                  type: string
                                  pattern: ^[a-z0-9_-]{1,64}$
                                  description: >-
                                    Unique within the session. Shows up in
                                    results and logs.
                                name:
                                  type: string
                                  minLength: 1
                                  maxLength: 120
                                  description: >-
                                    A readable name. The agent sees it when this
                                    hook blocks a call.
                                applies_to:
                                  anyOf:
                                    - type: string
                                      enum:
                                        - all
                                    - type: object
                                      properties:
                                        toolkits:
                                          type: array
                                          items:
                                            type: string
                                            minLength: 1
                                          minItems: 1
                                          description: Toolkit slugs
                                      required:
                                        - toolkits
                                      additionalProperties: false
                                  description: >-
                                    Which tools the hook covers: "all" for all
                                    of them, or only the listed toolkits.
                                handler:
                                  oneOf:
                                    - type: object
                                      properties:
                                        type:
                                          type: string
                                          enum:
                                            - condition_check
                                        condition:
                                          type: string
                                          minLength: 1
                                          maxLength: 2000
                                          description: >-
                                            What to block, written as a plain
                                            sentence. For example: "Sending email to
                                            anyone outside example.org".
                                        action:
                                          type: string
                                          enum:
                                            - block
                                      required:
                                        - type
                                        - condition
                                        - action
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        type:
                                          type: string
                                          enum:
                                            - prompt_injection_check
                                        action:
                                          type: string
                                          enum:
                                            - block
                                      required:
                                        - type
                                        - action
                                      additionalProperties: false
                                      description: >-
                                        Blocks a tool response that tries to
                                        manipulate the agent: override its
                                        instructions, change its role, or make
                                        it take actions the user didn't ask for.
                              required:
                                - type
                                - id
                                - applies_to
                                - handler
                              additionalProperties: false
                        maxItems: 20
                        description: Hooks that run on this session's tool calls.
                      preload:
                        type: object
                        properties:
                          tools:
                            anyOf:
                              - type: array
                                items:
                                  type: string
                              - type: string
                                enum:
                                  - all
                            description: >-
                              Explicit preloaded tool slugs, or "all" when the
                              session dynamically exposes all app tools allowed
                              by its filters.
                        required:
                          - tools
                        additionalProperties: false
                        description: >-
                          Preload configuration. Explicit slugs are returned as
                          an array; dynamic preload is returned as "all".
                      connected_accounts:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                            format: connectedAccountId
                          minItems: 1
                        description: >-
                          Per-toolkit connected account overrides (array of
                          nano-IDs). Multi-account sessions can pin more than
                          one account per toolkit; otherwise length is 1.
                      search:
                        type: object
                        properties:
                          enable:
                            type: boolean
                            default: true
                        description: Search helper configuration
                      execute:
                        type: object
                        properties:
                          enable_multi_execute:
                            type: boolean
                            default: true
                        description: Execute helper configuration
                    required:
                      - user_id
                      - instant
                      - preload
                      - search
                      - execute
                    description: The configuration used to create this session
                  config_version:
                    type: integer
                    description: >-
                      Monotonic version of the config. Incremented on each
                      PATCH. Use for optimistic concurrency control.
                  experimental:
                    type: object
                    properties:
                      assistive_prompt:
                        type: string
                        description: >-
                          The assistive system prompt for the tool router
                          session
                      custom_toolkits:
                        type: array
                        items:
                          type: object
                          properties:
                            slug:
                              type: string
                              minLength: 1
                              pattern: ^[a-zA-Z0-9_-]+$
                            name:
                              type: string
                              minLength: 1
                              maxLength: 128
                            description:
                              type: string
                              minLength: 1
                              maxLength: 2048
                            tools:
                              type: array
                              items:
                                type: object
                                properties:
                                  slug:
                                    type: string
                                    description: >-
                                      Prefixed tool slug (e.g.
                                      LOCAL_CRM_FIND_CUSTOMER)
                                  name:
                                    type: string
                                    minLength: 1
                                    maxLength: 128
                                  description:
                                    type: string
                                    minLength: 1
                                    maxLength: 5120
                                  input_schema:
                                    type: object
                                    additionalProperties: {}
                                  output_schema:
                                    type: object
                                    additionalProperties: {}
                                  original_slug:
                                    type: string
                                    description: Original tool slug as provided by the user
                                  preload:
                                    type: boolean
                                    description: >-
                                      Echoes the SDK-local preload hint provided
                                      for this tool
                                required:
                                  - slug
                                  - name
                                  - description
                                  - input_schema
                                  - original_slug
                            preload:
                              type: boolean
                              description: >-
                                Echoes the SDK-local preload hint provided for
                                this toolkit
                          required:
                            - slug
                            - name
                            - description
                            - tools
                        description: >-
                          User-defined custom toolkits with grouped tools
                          (no-auth)
                      custom_tools:
                        type: array
                        items:
                          type: object
                          properties:
                            slug:
                              type: string
                              description: >-
                                Prefixed tool slug (e.g.
                                LOCAL_GMAIL_GET_IMPORTANT_EMAILS)
                            name:
                              type: string
                              minLength: 1
                              maxLength: 128
                            description:
                              type: string
                              minLength: 1
                              maxLength: 5120
                            input_schema:
                              type: object
                              additionalProperties: {}
                            output_schema:
                              type: object
                              additionalProperties: {}
                            extends_toolkit:
                              type: string
                              minLength: 1
                            original_slug:
                              type: string
                              description: Original tool slug as provided by the user
                            preload:
                              type: boolean
                              description: >-
                                Echoes the SDK-local preload hint provided for
                                this tool
                          required:
                            - slug
                            - name
                            - description
                            - input_schema
                            - original_slug
                        description: >-
                          Custom tools — standalone or extending Composio
                          toolkits
                      no_elicitation_support_fallback:
                        type: string
                        enum:
                          - deny
                          - allow
                        description: >-
                          What session MCP does with a tool call that needs
                          approval when the MCP client can't ask the user.
                          Omitted when not set, which means deny.
                        x-experimental: true
                      source_session_config:
                        type: object
                        properties:
                          id:
                            type: string
                            format: sessionConfigId
                        required:
                          - id
                        description: >-
                          Experimental provenance for the reusable Session
                          config most recently applied to this Session.
                        x-experimental: true
                    description: Experimental v3.1 features
                    x-experimental: true
                  warnings:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          enum:
                            - PRELOAD_TOOLS_HIGH_CONTEXT_USAGE
                          description: >-
                            Stable machine code identifying the advisory. Safe
                            to switch on in client code.
                          example: PRELOAD_TOOLS_HIGH_CONTEXT_USAGE
                        message:
                          type: string
                          description: >-
                            Human-readable description of the advisory. Suitable
                            for logging or surfacing to end users.
                          example: >-
                            Session preloads 25 tools; each preloaded tool adds
                            to the agent context window. Consider keeping the
                            list at or under ~20 tools.
                      required:
                        - code
                        - message
                    default: []
                    description: >-
                      Advisory list — the session exists and is usable, but the
                      listed issues may warrant attention.
                    example:
                      - code: PRELOAD_TOOLS_HIGH_CONTEXT_USAGE
                        message: >-
                          Session preloads 25 tools; each preloaded tool adds to
                          the agent context window. Consider keeping the list at
                          or under ~20 tools.
                required:
                  - session_id
                  - mcp
                  - tool_router_tools
                  - config
                  - config_version
        '400':
          description: >-
            Bad request. This may occur if the session_id format is invalid,
            please pass this in trs_ prefix format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: >-
            Unauthorized. Authentication is required or the provided credentials
            are invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: >-
            Not found. The session with the provided ID does not exist or has
            been deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: >-
            Internal server error. An unexpected error occurred while processing
            the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            code:
              type: number
            slug:
              type: string
            status:
              type: number
            request_id:
              type: string
            suggested_fix:
              type: string
            errors:
              type: array
              items:
                type: string
          required:
            - message
            - code
            - slug
            - status
      required:
        - error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your Composio project API key. Create or copy it from the Composio
        dashboard.
      x-default: your-project-api-key

````