Skip to main content
POST
Execute a tool within a tool router session

Authorizations

x-api-key
string
header
default:your-project-api-key
required

Your Composio project API key. Create or copy it from the Composio dashboard.

Path Parameters

session_id
string<toolRouterSessionId>
required

Tool router session ID (required for public API, optional for internal - injected by middleware) 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"

Body

application/json
tool_slug
string
required

The unique slug identifier of the tool to execute. Supports both meta tools and app tools exposed by the session.

Minimum string length: 1
Example:

"GITHUB_CREATE_AN_ISSUE"

arguments
object

The arguments required by the tool

Example:
account
string

Account identifier to specify which connected account to use for direct tool execution. Use the account ID (e.g. "coup_hurricane_dal_analytical") or an alias. When omitted with a single account, the default is used. When omitted with multiple accounts, an error lists available accounts. Meta/helper tools either ignore this top-level field or define their own account-selection fields, for example COMPOSIO_MULTI_EXECUTE_TOOL.tools[].account.

Example:

"coup_hurricane_dal_analytical"

enable_auto_workbench_offload
boolean

When true, direct non-meta tool execution may return a workbench offload preview if the response exceeds the configured threshold and the session workbench is enabled. When omitted or false, direct tool execution returns the normal inline response. Meta/helper tools are unaffected, and COMPOSIO_MULTI_EXECUTE_TOOL uses session.workbench configuration for its own batch-level offload behavior.

Example:

true

input_responses
object

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.

Example:
request_state
string

The request_state from the input_required response, sent back unchanged with input_responses.

experimental
object

Inline custom tools and toolkits for this request. v3.1 sessions do not persist customs — pass them on every request that needs them.

Response

The tool call completed, failed, or needs the user's input before it can run. The result_type field says which of these happened.

result_type
enum<string>
required

The tool ran and succeeded

Available options:
completed
data
object
required

The data returned by the tool execution

Example:
error
string | null
required

Error message if the execution failed, null otherwise

log_id
string
required

Unique identifier for the execution log

Example:

"log_abc123xyz"

instant_charge
object

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.

hook_results
object[]

Every session hook that applied to this call. Omitted when none applied.