session.proxyExecute() calls any HTTP endpoint on a toolkit your session can already reach, and Composio injects the authentication (OAuth token, API key, basic auth, and so on) on the server side. Your code never handles raw credentials.
The session is already scoped to a userID, so you pass a toolkit slug rather than an account ID. Composio resolves the user’s connected account for that toolkit and signs the request with it.
Proxy execute is a building block, not just a fallback. Use it to build experiences on top of Composio that reach past predefined tools, like the Pi + Slack bot example, which drops down to the proxy for the Slack Web API calls the toolkit doesn’t wrap as tools. We’ll link more examples here as we add them.
For the complete connection-to-request flow in your own backend, follow Managed authentication for your own tools. It covers per-user OAuth, connection status, and account-specific proxy requests without an agent framework.
Use a scoped API keyAuthenticate with a scoped project API key that has Proxy execute enabled. Session tool execution alone does not cover
session.proxyExecute() or proxy calls made from that session’s sandbox. Default full-access keys already include this permission.When to use it
For a profile lookup during onboarding, use the proxy with the exact connected account ID you just created. See Identify the connected account and the Gmail domain restriction example for this account-specific flow.- Endpoints with no predefined tool. You need a specific endpoint (an unusual GitHub, LinkedIn, or Notion route) that isn’t exposed as a Composio tool. Send it through the proxy instead of extracting the raw token and calling the API yourself.
- Request shapes a tool can’t express. Custom query parameters, partial field masks, or advanced filters on Gmail, Drive, Sheets, and similar. The proxy gives you the full HTTP surface of the upstream API while Composio keeps managing auth.
Quick start
- Python
- TypeScript
- API
endpoint is a path relative to the toolkit’s base URL (/repos/... resolves against api.github.com). Pass an absolute URL only when you need a host that isn’t the toolkit’s standard API, such as a regional Salesforce or Zendesk domain.
Exposing proxy execution to your agent
SetproxyExecute: true (proxy_execute=True in Python) when creating a Session to expose the COMPOSIO_PROXY_EXECUTE meta tool:
- Python
- TypeScript
- API
{ enable: true } ({"enable": True} in Python). If you omit it at creation, the meta tool is off and sandbox.enableProxyExecution (sandbox.enable_proxy_execution in Python) controls the sandbox’s proxy_execute() helper.
The COMPOSIO_PROXY_EXECUTE meta tool uses different arguments from session.proxyExecute(): pass toolkit_slug instead of toolkit, put each parameter’s location in type instead of in, and method also accepts HEAD.
Failures come back as a tool result with successful: false and an error. An upstream non-2xx response returns normally in data, with its HTTP status and body. Large responses can be offloaded to the sandbox, as with other tool results.
Change the setting with session.update({ proxyExecute: false }) or Python session.update(proxy_execute=False). Disabling it also disables the sandbox helper. Pass null (None in Python) on update to remove the stored setting.
Session restrictions
Proxy execute follows the session’s toolkit lists: a call for a toolkit outsidetoolkits.enable or inside toolkits.disable is rejected with the same error a blocked tool call gets, including from the session’s sandbox.
Hint filters and per-toolkit tool rules do not apply, because a proxy request names an endpoint, not a tool. To remove the raw HTTP path from the session’s sandbox, turn proxy execution off in the sandbox config:
- Python
- TypeScript
- API
Parameters
Response shape
CheckresultType (result_type in Python) before reading HTTP response fields. A completed result forwards the upstream response’s status, headers, and parsed body. Both SDKs expose the same fields; TypeScript uses properties and Python uses dictionary keys.
A session hook can return blocked with a message and blockReason (block_reason in Python) instead of an HTTP response. The block reason’s type is request_blocked if the request was stopped before execution, or response_blocked if the request ran but its response was withheld. A blocked result has no status, data, headers, or binary data.
When the upstream returns a file, the binary entry carries
url, contentType, size, and expiresAt in TypeScript, and url, content_type, size, and expires_at in Python. expires_at may be absent in TypeScript and None in Python when the upstream gives no expiry. The key is absent entirely when the response is not a file, so check for it before reading:
- Python
- TypeScript
- API
Error handling
For completed results,status and data reflect what the toolkit API returned. Check status and branch on the common failures.
If the call needs user input before it can run, the SDK raises ToolInputRequiredError in Python or ComposioToolInputRequiredError in TypeScript instead of returning an HTTP response. Nothing was executed. See Handling requests for user input for the error fields and continuation state.
Composio sends a proxied call exactly once. A timeout, a connection error, or a
5xx surfaces to you rather than being retried, because a retry after the upstream API already acted would repeat the write. Retry only when the endpoint is safe to call again. See Retry failed executions deliberately.