Proxy execute

Proxy execute lets you call any HTTP endpoint on a supported toolkit using a connected account. Composio injects the authentication (OAuth token, API key, basic auth, etc.) on the server side, so your code never handles raw credentials.

Use it when you need an endpoint that Composio's predefined tools do not cover, or when you want the flexibility of a raw HTTP call while keeping Composio as the source of truth for user auth.

When to use proxy execute

1. Endpoints not covered by a predefined tool

You need a specific endpoint on a toolkit (for example, an unusual LinkedIn or Notion endpoint) that isn't exposed as a predefined Composio tool. Instead of extracting the raw OAuth token and making the call yourself, send the request through proxy execute and let Composio attach credentials.

# Fetch the authenticated user's LinkedIn profile
response = composio.tools.proxy(
    endpoint="/v2/userinfo",
    method="GET",
    connected_account_id="ca_linkedin_user_123",
)

print(response["data"])

// Fetch the authenticated user's LinkedIn profile
const { data } = await composio.tools.proxyExecute({
  endpoint: '/v2/userinfo',
  method: 'GET',
  connectedAccountId: 'ca_linkedin_user_123',
});

console.log(data);

2. Request shapes a predefined tool cannot express

AI workflows that talk to Gmail, Drive, Sheets, Outlook, or Teams often need request shapes beyond the pre-built actions — custom query parameters, partial field masks, advanced filters. Proxy execute gives you the full HTTP surface of the upstream API while keeping auth managed by Composio.

# Read a Google Sheet range with custom render options
response = composio.tools.proxy(
    endpoint="/v4/spreadsheets/1abc.../values/Sheet1!A1:D100",
    method="GET",
    connected_account_id="ca_googlesheets_user_123",
    parameters=[
        {"name": "valueRenderOption", "value": "UNFORMATTED_VALUE", "type": "query"},
        {"name": "dateTimeRenderOption", "value": "SERIAL_NUMBER", "type": "query"},
    ],
)

print(response["data"])

// Read a Google Sheet range with custom render options
const { data } = await composio.tools.proxyExecute({
  endpoint: '/v4/spreadsheets/1abc.../values/Sheet1!A1:D100',
  method: 'GET',
  connectedAccountId: 'ca_googlesheets_user_123',
  parameters: [
    { name: 'valueRenderOption', value: 'UNFORMATTED_VALUE', in: 'query' },
    { name: 'dateTimeRenderOption', value: 'SERIAL_NUMBER', in: 'query' },
  ],
});

console.log(data);

3. Terminal and CLI agents that would otherwise use raw tokens

Agents running in a terminal often fall back to curl calls with a hardcoded bearer token. Replacing that with a call to Composio's proxy endpoint keeps user credentials server-side — no tokens in shell history, env files, or process state.

curl --location 'https://backend.composio.dev/api/v3.1/tools/execute/proxy' \
  --header "x-api-key: $COMPOSIO_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "endpoint": "/user/repos",
    "method": "GET",
    "connected_account_id": "ca_github_user_123",
    "parameters": [
      { "name": "per_page", "value": "50", "type": "query" },
      { "name": "sort",     "value": "updated", "type": "query" }
    ]
  }'

Quick start

from composio import Composio

composio = Composio(api_key="your_api_key")

response = composio.tools.proxy(
    endpoint="/repos/composiohq/composio/issues/1",
    method="GET",
    connected_account_id="ca_github_user_123",
    parameters=[
        {"name": "Accept", "value": "application/vnd.github.v3+json", "type": "header"},
    ],
)

print(response["status"])
print(response["data"])

import { Composio } from '@composio/core';

const composio = new Composio({ apiKey: 'your_api_key' });

const { status, data } = await composio.tools.proxyExecute({
  endpoint: '/repos/composiohq/composio/issues/1',
  method: 'GET',
  connectedAccountId: 'ca_github_user_123',
  parameters: [
    { name: 'Accept', value: 'application/vnd.github.v3+json', in: 'header' },
  ],
});

console.log(status);
console.log(data);

The endpoint can be an absolute URL (https://api.example.com/v1/resource) or a relative path (/v1/resource). Relative paths are resolved against the toolkit's default base URL — only use the absolute form when calling a host that isn't the toolkit's standard API (for example, a regional Salesforce or Zendesk domain).

Parameters

The full schema is documented in the POST /api/v3.1/tools/execute/proxy reference.

Response shape

{
  "data": { /* parsed JSON body returned by the upstream API */ },
  "status": 200,
  "headers": { "content-type": "application/json", "...": "..." },
  "binary_data": {
    "url": "https://...",
    "content_type": "application/pdf",
    "size": 12345,
    "expires_at": "2026-01-01T00:00:00Z"
  }
}

binary_data is only present when the upstream API returns a binary response (PDFs, images, etc.). See Binary data support for details.

Common patterns

GET with query parameters

response = composio.tools.proxy(
    endpoint="/search/issues",
    method="GET",
    connected_account_id="ca_github_user_123",
    parameters=[
        {"name": "q", "value": "is:open label:bug repo:composiohq/composio", "type": "query"},
        {"name": "per_page", "value": "20", "type": "query"},
    ],
)

const { data } = await composio.tools.proxyExecute({
  endpoint: '/search/issues',
  method: 'GET',
  connectedAccountId: 'ca_github_user_123',
  parameters: [
    { name: 'q', value: 'is:open label:bug repo:composiohq/composio', in: 'query' },
    { name: 'per_page', value: '20', in: 'query' },
  ],
});

POST with a JSON body

response = composio.tools.proxy(
    endpoint="/repos/composiohq/composio/issues",
    method="POST",
    connected_account_id="ca_github_user_123",
    body={
        "title": "Found a bug",
        "body": "Steps to reproduce: ...",
        "labels": ["bug"],
    },
)

const { data } = await composio.tools.proxyExecute({
  endpoint: '/repos/composiohq/composio/issues',
  method: 'POST',
  connectedAccountId: 'ca_github_user_123',
  body: {
    title: 'Found a bug',
    body: 'Steps to reproduce: ...',
    labels: ['bug'],
  },
});

Custom headers

Add vendor-specific headers (API versions, accept types, correlation IDs) via parameters with type: "header".

response = composio.tools.proxy(
    endpoint="/crm/v3/objects/contacts",
    method="GET",
    connected_account_id="ca_hubspot_user_123",
    parameters=[
        {"name": "Accept", "value": "application/json", "type": "header"},
        {"name": "X-Request-Id", "value": "req_abc123", "type": "header"},
        {"name": "limit", "value": "100", "type": "query"},
    ],
)

const { data } = await composio.tools.proxyExecute({
  endpoint: '/crm/v3/objects/contacts',
  method: 'GET',
  connectedAccountId: 'ca_hubspot_user_123',
  parameters: [
    { name: 'Accept', value: 'application/json', in: 'header' },
    { name: 'X-Request-Id', value: 'req_abc123', in: 'header' },
    { name: 'limit', value: '100', in: 'query' },
  ],
});

Uploading a file

Use binary_body to upload binary content. You can point at a URL that Composio fetches server-side, or inline the bytes as base64.

curl --location 'https://backend.composio.dev/api/v3.1/tools/execute/proxy' \
  --header "x-api-key: $COMPOSIO_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "endpoint": "/upload",
    "method": "POST",
    "connected_account_id": "ca_abc123",
    "binary_body": { "url": "https://example.com/report.pdf" }
  }'

See the binary data changelog entry for the full upload and download flow.

Error handling

Proxy execute forwards the upstream response verbatim — status, headers, and data reflect what the toolkit API returned. Check status and branch on the common failures.

What to read next