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

> Executes a specific tool within a tool router session. This is the primary execution endpoint for both meta tools and app tools exposed by the session. The toolkit is automatically inferred from the tool slug. For app tools, the tool must belong to an allowed toolkit and must not be disabled in the session configuration. The endpoint validates permissions, resolves connected accounts when needed, and executes the tool with the session context. The top-level account field applies only to direct app tool execution in multi-account sessions. Meta/helper tools either ignore it or define their own account-selection fields, for example COMPOSIO_MULTI_EXECUTE_TOOL.tools[].account.



## OpenAPI

````yaml api-reference/openapi-v3.json POST /api/v3/tool_router/session/{session_id}/execute
openapi: 3.0.0
info:
  version: 3.0.0
  title: Composio Platform API
  description: >-
    Composio v3 API — legacy endpoints under /api/v3/. Use v3.1 for new
    integrations.
  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: Organization Management
    description: Organization Management API endpoints.
    x-group: Organization Management
  - name: Projects
    description: Projects API endpoints.
    x-group: Projects
paths:
  /api/v3/tool_router/session/{session_id}/execute:
    post:
      tags:
        - Tool Router
      summary: Execute a tool within a tool router session
      description: >-
        Executes a specific tool within a tool router session. This is the
        primary execution endpoint for both meta tools and app tools exposed by
        the session. The toolkit is automatically inferred from the tool slug.
        For app tools, the tool must belong to an allowed toolkit and must not
        be disabled in the session configuration. The endpoint validates
        permissions, resolves connected accounts when needed, and executes the
        tool with the session context. The top-level account field applies only
        to direct app tool execution in multi-account sessions. Meta/helper
        tools either ignore it or define their own account-selection fields, for
        example COMPOSIO_MULTI_EXECUTE_TOOL.tools[].account.
      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
              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
          nullable: true
          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
          nullable: true
          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

````