# Execute proxy request

**Documentation:** /reference/api-reference/tools/postToolsExecuteProxy

Proxy an HTTP request to a third-party API using connected account credentials. This endpoint allows making authenticated API calls to external services while abstracting away authentication details.

---

## POST `/api/v3/tools/execute/proxy`

**Endpoint:** `https://backend.composio.dev/api/v3/tools/execute/proxy`

**Summary:** Execute proxy request

Proxy an HTTP request to a third-party API using connected account credentials. This endpoint allows making authenticated API calls to external services while abstracting away authentication details.

### Authentication

**ApiKeyAuth** - API Key in `header` header `x-api-key` OR **UserApiKeyAuth** - API Key in `header` header `x-user-api-key`

### Request Body

**Schema:**

- `connected_account_id` (string (connectedAccountId)): The ID of the connected account to use for authentication (if not provided, will use the default account for the project)
- `endpoint` (string) *(required)*: The API endpoint to call (absolute URL or path relative to base URL of the connected account)
- `method` (enum: "GET" | "POST" | "PUT" | ...) *(required)*: The HTTP method to use for the request
- `body` (object,null): The request body (for POST, PUT, and PATCH requests)
- `binary_body` (any): Binary body to send. For binary upload via URL: use {url: "https://...", content_type?: "..."}. For binary upload via base64: use {base64: "...", content_type?: "..."}.
- `parameters` (array<object>): Additional HTTP headers or query parameters to include in the request
  - Array items:
    - `name` (string) *(required)*: Parameter name
    - `value` (string) *(required)*: Parameter value
    - `type` (enum: "header" | "query") *(required)*: Parameter type (header or query)
- `custom_connection_data` (object)
  - `authScheme` (enum: "OAUTH2" | "DCR_OAUTH" | "API_KEY" | ...) *(required)*
  - `toolkitSlug` (string) *(required)*
  - `val` (object) *(required)*
    - `subdomain` (string)
    - `your-domain` (string)
    - `region` (string)
    - `shop` (string)
    - `account_url` (string)
    - `COMPANYDOMAIN` (string)
    - `extension` (string)
    - `form_api_base_url` (string)
    - `instanceEndpoint` (string)
    - `api_url` (string)
    - `borneo_dashboard_url` (string)
    - `proxy_username` (string)
    - `proxy_password` (string)
    - `domain` (string)
    - `version` (string)
    - `dc` (string)
    - `site_name` (string)
    - `instanceName` (string)
    - `account_id` (string)
    - `your_server` (string)
    - `server_location` (string)
    - `base_url` (string)
    - `state_prefix` (string): The oauth2 state prefix for the connection
    - `long_redirect_url` (boolean): Whether to return the redirect url without shortening
    - `access_token` (string) *(required)*
    - `id_token` (string)
    - `token_type` (string)
    - `refresh_token` (string,null)
    - `expires_in` (any)
    - `scope` (any)
    - `webhook_signature` (string)
    - `authed_user` (object): for slack user scopes
      - `access_token` (string)
      - `scope` (string)
    - `client_id` (string): Dynamically registered client ID
    - `client_secret` (string): Dynamically registered client secret
    - `client_id_issued_at` (number)
    - `client_secret_expires_at` (number)
    - `generic_api_key` (string)
    - `api_key` (string)
    - `bearer_token` (string)
    - `basic_encoded` (string)
    - `username` (string)
    - `password` (string)
    - `token` (string)
    - `oauth_token` (string)
    - `oauth_token_secret` (string)
    - `oauth_verifier` (string)
    - `consumer_key` (string)
    - `redirectUrl` (string)
    - `callback_url` (string)
    - `application_id` (string)
    - `installation_id` (string)
    - `private_key` (string)
    - `credentials_json` (string)
    - `expires_at` (string)
    - `[key: string]` (any)

**Example:**

```json
{
  "connected_account_id": "string",
  "endpoint": "string",
  "method": "GET",
  "body": null,
  "binary_body": null,
  "parameters": [
    {
      "name": "string",
      "value": "string",
      "type": "header"
    }
  ],
  "custom_connection_data": {
    "authScheme": "OAUTH2",
    "toolkitSlug": "string",
    "val": {
      "subdomain": "string",
      "your-domain": "string",
      "region": "string",
      "shop": "string",
      "account_url": "string",
      "COMPANYDOMAIN": "string",
      "extension": "string",
      "form_api_base_url": "string",
      "instanceEndpoint": "string",
      "api_url": "string",
      "borneo_dashboard_url": "string",
      "proxy_username": "string",
      "proxy_password": "string",
      "domain": "string",
      "version": "string",
      "dc": "string",
      "site_name": "string",
      "instanceName": "string",
      "account_id": "string",
      "your_server": "string",
      "server_location": "string",
      "base_url": "string",
      "state_prefix": "string",
      "long_redirect_url": true,
      "access_token": "string",
      "id_token": "string",
      "token_type": "string",
      "refresh_token": null,
      "expires_in": null,
      "scope": null,
      "webhook_signature": "string",
      "authed_user": {
        "access_token": "...",
        "scope": "..."
      },
      "client_id": "string",
      "client_secret": "string",
      "client_id_issued_at": 1,
      "client_secret_expires_at": 1,
      "generic_api_key": "string",
      "api_key": "string",
      "bearer_token": "string",
      "basic_encoded": "string",
      "username": "string",
      "password": "string",
      "token": "string",
      "oauth_token": "string",
      "oauth_token_secret": "string",
      "oauth_verifier": "string",
      "consumer_key": "string",
      "redirectUrl": "string",
      "callback_url": "string",
      "application_id": "string",
      "installation_id": "string",
      "private_key": "string",
      "credentials_json": "string",
      "expires_at": "string",
      "key": null
    }
  }
}
```

### Responses

#### 200 - Successfully executed proxy request and received response

**Response Schema:**

- `data` (object,null): The response data returned from the proxied API
- `binary_data` (object): Binary body response data. Present when the response is a binary file.
  - `url` (string) *(required)*: URL to download binary content
  - `content_type` (string) *(required)*: Content-Type of the binary data
  - `size` (number) *(required)*: File size in bytes
  - `expires_at` (string): ISO 8601 timestamp when the URL expires
- `status` (number) *(required)*: The HTTP status code returned from the proxied API
- `headers` (object): The HTTP headers returned from the proxied API
  - `[key: string]` (string)

**Example Response:**

```json
{
  "data": null,
  "binary_data": {
    "url": "string",
    "content_type": "string",
    "size": 1,
    "expires_at": "string"
  },
  "status": 1,
  "headers": {
    "key": "string"
  }
}
```

#### 400 - Bad request - Invalid request parameters or body format

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 401 - Unauthorized - Authentication credentials are missing or invalid

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 403 - Forbidden - Connected account does not have permission to access the requested resource

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 404 - Not found - Resource not found or connected account not found

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 422 - Unprocessable entity - Invalid state of the connected account

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 429 - Too many requests - Rate limit exceeded on the connected account or proxy service

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 500 - Internal server error - Something went wrong on the server

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 501 - Not implemented - This operation is not supported for the requested connected account or authentication scheme

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 502 - Bad gateway - Error communicating with the upstream API

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 504 - Gateway timeout - Upstream API timed out

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

### Example cURL Request

```bash
curl -X POST "https://backend.composio.dev/api/v3/tools/execute/proxy" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connected_account_id": "string",
    "endpoint": "string",
    "method": "GET",
    "body": null,
    "binary_body": null,
    "parameters": [
      {
        "name": "string",
        "value": "string",
        "type": "header"
      }
    ],
    "custom_connection_data": {
      "authScheme": "OAUTH2",
      "toolkitSlug": "string",
      "val": {
        "subdomain": "string",
        "your-domain": "string",
        "region": "string",
        "shop": "string",
        "account_url": "string",
        "COMPANYDOMAIN": "string",
        "extension": "string",
        "form_api_base_url": "string",
        "instanceEndpoint": "string",
        "api_url": "string",
        "borneo_dashboard_url": "string",
        "proxy_username": "string",
        "proxy_password": "string",
        "domain": "string",
        "version": "string",
        "dc": "string",
        "site_name": "string",
        "instanceName": "string",
        "account_id": "string",
        "your_server": "string",
        "server_location": "string",
        "base_url": "string",
        "state_prefix": "string",
        "long_redirect_url": true,
        "access_token": "string",
        "id_token": "string",
        "token_type": "string",
        "refresh_token": null,
        "expires_in": null,
        "scope": null,
        "webhook_signature": "string",
        "authed_user": {
          "access_token": "...",
          "scope": "..."
        },
        "client_id": "string",
        "client_secret": "string",
        "client_id_issued_at": 1,
        "client_secret_expires_at": 1,
        "generic_api_key": "string",
        "api_key": "string",
        "bearer_token": "string",
        "basic_encoded": "string",
        "username": "string",
        "password": "string",
        "token": "string",
        "oauth_token": "string",
        "oauth_token_secret": "string",
        "oauth_verifier": "string",
        "consumer_key": "string",
        "redirectUrl": "string",
        "callback_url": "string",
        "application_id": "string",
        "installation_id": "string",
        "private_key": "string",
        "credentials_json": "string",
        "expires_at": "string",
        "key": null
      }
    }
  }'
```