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

# Proxy execute

> Call any API endpoint on a toolkit from a session and let Composio inject the authenticated credentials for you

`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](https://composio-preview.mintlify.site/docs/how-composio-works.md), 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](https://composio-preview.mintlify.site/examples/general-agent-with-pi.md#reach-the-gaps-with-the-proxy), 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](https://composio-preview.mintlify.site/docs/authentication/managed-auth-for-custom-tools.md). It covers per-user OAuth, connection status, and account-specific proxy requests without an agent framework.

> [!NOTE]
>
> **Use a scoped API key**
>
> Authenticate with a [scoped project API key](https://composio-preview.mintlify.site/reference/authenticating-to-composio/project-api-key-permissions.md) 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](https://composio-preview.mintlify.site/docs/authentication/manually-authenticating.md#identify-the-connected-account) and the [Gmail domain restriction example](https://composio-preview.mintlify.site/examples/restrict-gmail-domain.md) 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

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
>
> composio = Composio(api_key="your_api_key")
> session = composio.create(user_id="user_123", toolkits=["github"])
>
> response = session.proxy_execute(
>     toolkit="github",
>     endpoint="/repos/composiohq/composio/issues/1",
>     method="GET",
>     parameters=[
>         {"name": "Accept", "value": "application/vnd.github.v3+json", "in": "header"},
>     ],
> )
>
> # A session hook can block the request; only a completed result has a response.
> if response["result_type"] == "completed":
>     print(response["status"])
>     print(response["data"])
> else:
>     print(response["message"])
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create('user_123', { toolkits: ['github'] });
> const response = await session.proxyExecute({
>   toolkit: 'github',
>   endpoint: '/repos/composiohq/composio/issues/1',
>   method: 'GET',
>   parameters: [
>     { name: 'Accept', value: 'application/vnd.github.v3+json', in: 'header' },
>   ],
> });
>
> if (response.resultType === 'completed') {
>   console.log(response.status);
>   console.log(response.data);
> } else {
>   console.log(response.message);
> }
> ```

> [tab] API
>
> ```bash theme={null}
> SESSION_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"user_id": "user_123", "toolkits": {"enable": ["github"]}}' | jq -r '.session_id')
>
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/proxy_execute \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "toolkit_slug": "github",
>     "endpoint": "/repos/composiohq/composio/issues/1",
>     "method": "GET",
>     "parameters": [
>       {"name": "Accept", "value": "application/vnd.github.v3+json", "type": "header"}
>     ]
>   }'
> ```

The `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.

> [!WARNING]
>
> **Don't repeat the base URL's path**
>
> The `endpoint` is appended to the base URL, and many base URLs already include a path. Google Calendar's base URL is `https://www.googleapis.com/calendar/v3`, so pass `/users/me/calendarList`. Passing `/calendar/v3/users/me/calendarList` requests `/calendar/v3/calendar/v3/users/me/calendarList` and returns a `404`.

> [!WARNING]
>
> Proxy execute rejects cross-domain requests. The `endpoint` must resolve to the same domain as the toolkit's connected account (a GitHub connection can only call `api.github.com` paths). This is an intentional security boundary, not a quota, so you can't work around it by reshaping the request.

## Exposing proxy execution to your agent

Set `proxyExecute: true` (`proxy_execute=True` in Python) when creating a Session to expose the `COMPOSIO_PROXY_EXECUTE` meta tool:

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
>
> composio = Composio(api_key="your_api_key")
> session = composio.create(user_id="user_123", toolkits=["github"], proxy_execute=True)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123", {
>   toolkits: ["github"],
>   proxyExecute: true,
> });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"user_id": "user_123", "toolkits": {"enable": ["github"]}, "proxy_execute": {"enable": true}}'
> ```

The option also accepts `{ 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`](https://composio-preview.mintlify.site/toolkits/meta-tools/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](https://composio-preview.mintlify.site/docs/sandbox/remote.md), 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.

> [!WARNING]
>
> At creation, the API rejects a disabled proxy setting combined with an enabled sandbox proxy setting. Disable both, or omit the sandbox proxy setting.

## Session restrictions

Proxy execute follows the session's toolkit lists: a call for a toolkit outside `toolkits.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:

> [tab] Python
>
> ```python theme={null}
> session = composio.create(
>     user_id="user_123",
>     tags=["readOnlyHint"],
>     sandbox={"enable": True, "enable_proxy_execution": False},
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123", {
>   tags: ["readOnlyHint"],
>   sandbox: { enable: true, enableProxyExecution: false },
> });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "user_id": "user_123",
>     "tags": {"enable": ["readOnlyHint"]},
>     "workbench": {"enable": true, "enable_proxy_execution": false}
>   }'
> ```

## Parameters

| Parameter | Required | Type | Description |
| - | - | - | - |
| `toolkit` | Yes | `string` | Toolkit slug (`github`, `gmail`, and so on). Composio uses the session user's connected account for this toolkit. |
| `endpoint` | Yes | `string` | Path relative to the toolkit's base URL, or an absolute URL. |
| `method` | Yes | `"GET" \| "POST" \| "PUT" \| "PATCH" \| "DELETE"` | HTTP verb. |
| `body` | No | `object` | JSON request body. Used with `POST`, `PUT`, and `PATCH`. |
| `parameters` | No | `Array<{ name, value, in }>` | Extra headers or query parameters. `in` is `"header"` or `"query"`. |

## Response shape

Check `resultType` (`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.

| TypeScript | Python | Type | Description |
| - | - | - | - |
| `status` | `status` | `number` / `int` | HTTP status code from the upstream API. |
| `data` | `data` | `unknown` / `Any` | Parsed JSON body the API returned. Optional in TypeScript; in Python the key is always present but may be `None`. |
| `headers` | `headers` | `Record<string, string>` / `dict[str, str] \| None` | Response headers. Optional in TypeScript; in Python the key is always present but may be `None`. |
| `binaryData` | `binary_data` | `object` / `dict` | Present only when the upstream returns a file. |

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:

> [tab] Python
>
> ```python theme={null}
> if "binary_data" in response:
>     print(response["binary_data"]["url"])
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create('user_123', { toolkits: ['github'] });
> const response = await session.proxyExecute({
>   toolkit: 'github',
>   endpoint: '/repos/composiohq/composio/issues/1',
>   method: 'GET',
> });
> if (response.resultType === 'completed' && response.binaryData) {
>   console.log(response.binaryData.url);
> }
> ```

> [tab] API
>
> ```bash theme={null}
> # SESSION_ID is the session_id returned when you created the session
> curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/proxy_execute \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"toolkit_slug": "github", "endpoint": "/repos/composiohq/composio/issues/1", "method": "GET"}' \
>   | jq -r '.binary_data.url // empty'
> ```

> [!WARNING]
>
> Don't set the `Authorization` header yourself through `parameters`. Composio injects the correct one from the connected account's auth scheme, and setting it manually overrides that credential and usually produces a `401`.

## 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](https://composio-preview.mintlify.site/docs/how-composio-works.md#handling-requests-for-user-input) for the error fields and continuation state.

| Status | Typical cause | How to resolve |
| - | - | - |
| `400 Bad Request` | Malformed endpoint path, invalid body, or unsupported `method`. | Check the upstream API docs for the expected shape. The proxy doesn't validate upstream schemas. |
| `401 Unauthorized` | The connected account's token expired or was revoked. | Re-authenticate the user, or [import fresh credentials](https://composio-preview.mintlify.site/docs/authentication/importing-existing-connections.md). |
| `403 Forbidden` | The user's OAuth scopes or API key don't cover this endpoint. | Update the [auth config scopes](https://composio-preview.mintlify.site/docs/auth-configuration/custom-auth-configs.md) and have the user re-consent. |
| `429 Too Many Requests` | Upstream rate limit (GitHub, Google, and so on). | Honor the `Retry-After` header and back off. Composio doesn't retry automatically. |

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](https://composio-preview.mintlify.site/docs/production-readiness.md#retry-failed-executions-deliberately).

## Next

> [card] [Custom tools and toolkits](https://composio-preview.mintlify.site/docs/extending-sessions/custom-tools-and-toolkits.md)
>
> Define in-process tools and toolkits that run alongside Composio tools
