> ## 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.

# Execute a tool within a tool router session

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



## OpenAPI

````yaml /api-reference/openapi.json post /api/v3.1/tool_router/session/{session_id}/execute
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}/execute:
    post:
      tags:
        - Tool Router
      summary: Execute a tool within a tool router session
      description: Execute a tool (meta or app) within an existing tool router session.
      operationId: postToolRouterSessionBySessionIdExecute
      parameters:
        - schema:
            type: string
            format: toolRouterSessionId
            description: >-
              The unique identifier of the tool router session. Required for
              public API endpoints, optional for internal endpoints where it is
              injected by middleware.
            example: trs_LX9uJKBinWWr
          required: true
          description: >-
            Tool router session ID (required for public API, optional for
            internal - injected by middleware)
          name: session_id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                tool_slug:
                  type: string
                  minLength: 1
                  description: >-
                    The unique slug identifier of the tool to execute. Supports
                    both meta tools and app tools exposed by the session.
                  example: GITHUB_CREATE_AN_ISSUE
                arguments:
                  type: object
                  additionalProperties: {}
                  default: {}
                  description: The arguments required by the tool
                  example:
                    repository: octocat/Hello-World
                    workflow_id: main.yml
                    ref: main
                    inputs:
                      environment: production
                account:
                  type: string
                  description: >-
                    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.
                  example: coup_hurricane_dal_analytical
                enable_auto_workbench_offload:
                  type: boolean
                  description: >-
                    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.
                  example: true
                input_responses:
                  type: object
                  additionalProperties:
                    $ref: '#/components/schemas/UserInputResponse'
                  description: >-
                    The user's answers to an `input_required` response, keyed by
                    the ids in its `input_requests`. Send them by repeating the
                    same call (same tool and arguments) with this field added,
                    along with the response's `request_state` if present. An
                    approved call runs; a denied or declined one returns
                    `failed`.
                  x-experimental: true
                  example:
                    elicit_3f9a1c2b7d4e5f60:
                      action: accept
                      content:
                        decision: approve
                request_state:
                  type: string
                  description: >-
                    The `request_state` from the `input_required` response, sent
                    back unchanged with `input_responses`.
                  x-experimental: true
                experimental:
                  type: object
                  properties:
                    custom_toolkits:
                      type: array
                      items:
                        type: object
                        properties:
                          slug:
                            type: string
                            minLength: 1
                            pattern: ^[a-zA-Z0-9_-]+$
                            description: >-
                              Unique slug for the toolkit. Must not conflict
                              with existing Composio toolkit slugs.
                              Alphanumeric, underscores, and hyphens only.
                            example: ecommerce
                          name:
                            type: string
                            minLength: 1
                            maxLength: 128
                            description: >-
                              Display name shown to the LLM and in search
                              results.
                            example: E-Commerce API
                          description:
                            type: string
                            minLength: 1
                            maxLength: 2048
                            description: >-
                              Used for BM25 search matching and shown in toolkit
                              connection statuses.
                            example: >-
                              Internal e-commerce API for order management and
                              fulfillment
                          preload:
                            type: boolean
                            description: >-
                              SDK hint for direct custom-tool exposure. Not
                              stored in session config; echoed in create/attach
                              responses for inline custom definitions.
                          tools:
                            type: array
                            items:
                              type: object
                              properties:
                                slug:
                                  type: string
                                  minLength: 1
                                  pattern: ^[a-zA-Z0-9_-]+$
                                  description: >-
                                    Tool slug. Combined with toolkit slug to
                                    form LOCAL_<TOOLKIT>_<TOOL> (max 60 chars
                                    total).
                                  example: GET_CUSTOMER_ORDERS
                                name:
                                  type: string
                                  minLength: 1
                                  maxLength: 128
                                  description: Human-readable display name
                                  example: Get Customer Orders
                                description:
                                  type: string
                                  minLength: 1
                                  maxLength: 5120
                                  description: >-
                                    Used for BM25 search matching and shown to
                                    the LLM.
                                  example: >-
                                    Fetch recent orders for a customer by their
                                    email address
                                input_schema:
                                  type: object
                                  additionalProperties: {}
                                  description: >-
                                    Must have type: "object" and a properties
                                    field.
                                  example:
                                    type: object
                                    properties:
                                      email:
                                        type: string
                                        description: Customer email
                                    required:
                                      - email
                                output_schema:
                                  type: object
                                  additionalProperties: {}
                                  description: >-
                                    Optional output schema for the tool
                                    response.
                                preload:
                                  type: boolean
                                  description: >-
                                    SDK hint for direct custom-tool exposure.
                                    Not stored in session config; echoed in
                                    create/attach responses for inline custom
                                    definitions.
                              required:
                                - slug
                                - name
                                - description
                                - input_schema
                            minItems: 1
                            maxItems: 100
                            description: Tools in this custom toolkit
                        required:
                          - slug
                          - name
                          - description
                          - tools
                      description: >-
                        Custom toolkits with grouped tools. Toolkit slugs must
                        not conflict with existing Composio toolkits. All tools
                        are no-auth.
                    custom_tools:
                      type: array
                      items:
                        type: object
                        properties:
                          slug:
                            type: string
                            minLength: 1
                            pattern: ^[a-zA-Z0-9_-]+$
                            description: >-
                              Tool slug. Forms LOCAL_<TOOL> (standalone) or
                              LOCAL_<TOOLKIT>_<TOOL> (extending). Max 60 chars
                              total.
                            example: GET_IMPORTANT_EMAILS
                          name:
                            type: string
                            minLength: 1
                            maxLength: 128
                            description: Human-readable display name
                            example: Get Important Emails
                          description:
                            type: string
                            minLength: 1
                            maxLength: 5120
                            description: >-
                              Used for BM25 search matching and shown to the
                              LLM.
                            example: >-
                              Fetch emails marked as important from the last 24
                              hours
                          input_schema:
                            type: object
                            additionalProperties: {}
                            description: 'Must have type: "object" and a properties field.'
                            example:
                              type: object
                              properties:
                                limit:
                                  type: number
                                  description: Max results to return
                          output_schema:
                            type: object
                            additionalProperties: {}
                            description: JSON Schema describing tool output (optional)
                          extends_toolkit:
                            type: string
                            minLength: 1
                            description: >-
                              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).
                            example: gmail
                          preload:
                            type: boolean
                            description: >-
                              SDK hint for direct custom-tool exposure. Not
                              stored in session config; echoed in create/attach
                              responses for inline custom definitions.
                        required:
                          - slug
                          - name
                          - description
                          - input_schema
                      description: >-
                        Custom tools to include in search. Standalone tools need
                        no auth. Tools with extends_toolkit inherit the Composio
                        toolkit's connection.
                  additionalProperties: false
                  description: >-
                    Inline custom tools and toolkits for this request. v3.1
                    sessions do not persist customs — pass them on every request
                    that needs them.
              required:
                - tool_slug
      responses:
        '200':
          description: >-
            The tool call completed, failed, or needs the user's input before it
            can run. The `result_type` field says which of these happened.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ExecuteCompleted'
                  - $ref: '#/components/schemas/ExecuteFailed'
                  - $ref: '#/components/schemas/ExecuteBlocked'
                  - $ref: '#/components/schemas/ExecuteRequiresUserInput'
                discriminator:
                  propertyName: result_type
                  mapping:
                    completed: '#/components/schemas/ExecuteCompleted'
                    failed: '#/components/schemas/ExecuteFailed'
                    blocked: '#/components/schemas/ExecuteBlocked'
                    input_required: '#/components/schemas/ExecuteRequiresUserInput'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Payment required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '410':
          description: Gone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Bad gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    UserInputResponse:
      type: object
      properties:
        action:
          type: string
          enum:
            - accept
            - decline
            - cancel
          description: >-
            `accept` when the user submitted the form, `decline` when they said
            no, `cancel` when they dismissed it
        content:
          type: object
          additionalProperties: {}
          description: >-
            With `accept`, the user's answer: fields matching the question's
            `requested_schema`
      required:
        - action
      description: >-
        The user's answer to one question, in the shape of an MCP elicitation
        result
        (https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation).
    ExecuteCompleted:
      type: object
      properties:
        result_type:
          type: string
          enum:
            - completed
          description: The tool ran and succeeded
          x-experimental: true
        instant_charge:
          type: object
          properties:
            amount:
              type: string
              pattern: ^(0|[1-9]\d*)(\.\d{1,12})?$
              description: >-
                Instant charge in USD as an exact non-negative decimal string,
                with up to 12 fractional digits.
            currency:
              type: string
              enum:
                - USD
              description: Currency of the instant charge. Always USD.
            charged_by:
              type: string
              enum:
                - composio
              description: Entity charging for instant usage. Always composio.
          required:
            - amount
            - currency
            - charged_by
          description: >-
            Returned only when the session enables instant.return_instant_charge
            and a charge is available. Failed individual tool calls omit it.
            Multi-execute returns one aggregate of reported charges from
            eligible successful calls, even if another call fails.
        data:
          type: object
          additionalProperties: {}
          description: The data returned by the tool execution
          example:
            message: Hello, World!
            status: success
        error:
          type:
            - string
            - 'null'
          description: Error message if the execution failed, null otherwise
        log_id:
          type: string
          description: Unique identifier for the execution log
          example: log_abc123xyz
        hook_results:
          type: array
          items:
            $ref: '#/components/schemas/HookResult'
          description: >-
            Every session hook that applied to this call. Omitted when none
            applied.
      required:
        - result_type
        - data
        - error
        - log_id
    ExecuteFailed:
      type: object
      properties:
        result_type:
          type: string
          enum:
            - failed
          description: The tool ran and failed, or the user did not approve it
          x-experimental: true
        instant_charge:
          type: object
          properties:
            amount:
              type: string
              pattern: ^(0|[1-9]\d*)(\.\d{1,12})?$
              description: >-
                Instant charge in USD as an exact non-negative decimal string,
                with up to 12 fractional digits.
            currency:
              type: string
              enum:
                - USD
              description: Currency of the instant charge. Always USD.
            charged_by:
              type: string
              enum:
                - composio
              description: Entity charging for instant usage. Always composio.
          required:
            - amount
            - currency
            - charged_by
          description: >-
            Returned only when the session enables instant.return_instant_charge
            and a charge is available. Failed individual tool calls omit it.
            Multi-execute returns one aggregate of reported charges from
            eligible successful calls, even if another call fails.
        data:
          type: object
          additionalProperties: {}
          description: The data returned by the tool execution
          example:
            message: Hello, World!
            status: success
        error:
          type:
            - string
            - 'null'
          description: Error message if the execution failed, null otherwise
        log_id:
          type: string
          description: Unique identifier for the execution log
          example: log_abc123xyz
        hook_results:
          type: array
          items:
            $ref: '#/components/schemas/HookResult'
          description: >-
            Every session hook that applied to this call. Omitted when none
            applied.
      required:
        - result_type
        - data
        - error
        - log_id
    ExecuteBlocked:
      type: object
      properties:
        result_type:
          type: string
          enum:
            - blocked
          description: A session hook stopped the call
        reason:
          $ref: '#/components/schemas/BlockReason'
        message:
          type: string
          description: >-
            A message for the agent. It includes the hook's name, when it has
            one; the hook id is in `reason`.
          example: 'Blocked by session policy: No external email'
        log_id:
          type: string
          description: >-
            The execution log ID. Only set when the tool ran and its response
            was blocked.
        instant_charge:
          type: object
          properties:
            amount:
              type: string
              pattern: ^(0|[1-9]\d*)(\.\d{1,12})?$
              description: >-
                Instant charge in USD as an exact non-negative decimal string,
                with up to 12 fractional digits.
            currency:
              type: string
              enum:
                - USD
              description: Currency of the instant charge. Always USD.
            charged_by:
              type: string
              enum:
                - composio
              description: Entity charging for instant usage. Always composio.
          required:
            - amount
            - currency
            - charged_by
          description: >-
            Returned only when the session enables instant.return_instant_charge
            and a charge is available. Only set when the tool ran and its
            response was blocked.
        hook_results:
          type: array
          items:
            $ref: '#/components/schemas/HookResult'
          description: >-
            Every session hook that applied to this call. Omitted when none
            applied.
      required:
        - result_type
        - reason
        - message
    ExecuteRequiresUserInput:
      type: object
      properties:
        result_type:
          type: string
          enum:
            - input_required
          description: The call needs the user's input before it runs
          x-experimental: true
        input_requests:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/UserInputRequest'
          description: Questions for the user, keyed by an ID the answers must reuse
          x-experimental: true
        request_state:
          type: string
          description: Send this back unchanged in `request_state` with the answers
          x-experimental: true
      required:
        - result_type
        - input_requests
      description: >-
        The call needs the user's input before it runs. Returned only when the
        session is configured to ask for user approval before tool execution.
        Show each question in `input_requests` to the user, then repeat the same
        call with their answers in `input_responses`, along with this
        `request_state` if present.
      x-experimental: true
    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
    HookResult:
      oneOf:
        - type: object
          properties:
            id:
              type: string
              description: The hook id
            status:
              type: string
              enum:
                - evaluated
            outcome:
              type: string
              enum:
                - continue
                - block
              description: What the hook decided
          required:
            - id
            - status
            - outcome
        - type: object
          properties:
            id:
              type: string
              description: The hook id
            status:
              type: string
              enum:
                - unavailable
              description: The hook could not be evaluated
          required:
            - id
            - status
    BlockReason:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - request_blocked
              description: A before_execute hook stopped the call. The tool did not run.
            hook_id:
              type: string
          required:
            - type
            - hook_id
        - type: object
          properties:
            type:
              type: string
              enum:
                - response_blocked
              description: >-
                An after_execute hook stopped the call. The tool ran; its
                response was withheld.
            hook_id:
              type: string
          required:
            - type
            - hook_id
    UserInputRequest:
      type: object
      properties:
        type:
          type: string
          enum:
            - elicitation
          description: Always `elicitation`
        mode:
          type: string
          enum:
            - form
          description: >-
            Always `form`: collect the answer with a form built from
            `requested_schema`
        message:
          type: string
          description: Text to show the user
          example: |-
            Your agent wants to run the following tool:

            GITHUB_DELETE_A_REPOSITORY({"owner": "acme", "repo": "old-api"})
        requested_schema:
          type: object
          additionalProperties: {}
          description: >-
            JSON Schema for the answer. As in MCP form mode, it is a flat object
            whose fields are strings, numbers, booleans, or single- or
            multi-select enums.
      required:
        - type
        - mode
        - message
        - requested_schema
      description: >-
        A question for the user, in the shape of an MCP `elicitation/create`
        request in form mode
        (https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation).
        Show `message` to the user and collect an answer that matches
        `requested_schema`.
  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

````