---
title: "Execute Connection Proxy"
method: POST
path: "/api/connections/{id}/proxy"
tags: ["Connections"]
---

# Execute Connection Proxy

`POST /api/connections/{id}/proxy`

Proxies an HTTP request to a connection's underlying API using the connection's stored credentials, subject to per-connection rate limits and size caps.

This endpoint is intended for controlled passthrough use, not as a general
replacement for Polytomic's modeled endpoints. The request is executed with the
connection's stored credentials and inherited base URL, headers, and query
parameters.

Before building requests dynamically, call
[`GET /api/connections/{id}/proxy/info`](../../../../api-reference/connections/get-proxy-info)
to inspect the inherited base URL, blocked headers, accepted body types, and
size and rate limits.

## Important behavior

- `request.path` must be relative and start with `/`.
- Use either `request.query` or `request.rawQuery`, not both.
- Caller-supplied headers are merged with inherited headers, but inherited auth
  headers cannot be overridden.
- The proxy strips a fixed set of request and response headers for safety.
- Response bodies larger than the configured maximum are truncated, and
  `truncated` is set to `true`.

To run a `GET` request asynchronously, set `async` to `true`. The initial
response returns `status: 202`, `jobId`, `jobStatus`, and `jobUrl`. Poll
[`GET /api/jobs/{type}/{id}`](../../../../api-reference/jobs/get-job) with
`type=connectionproxy` and the returned `jobId` until the job is complete. The
completed job result includes the upstream `status`, sanitized `headers`,
`contentType`, `contentLength`, `latencyMs`, and a short-lived
`bodyDownloadUrl` for the upstream response body.

The response includes `proxyCallId`, which you can use to correlate the call
with audit logs.

## Path parameters

- `id` string, uuid, required — Unique identifier of the connection to proxy the request through.

## Headers

- `X-Polytomic-Version` string

## Request body

- ExecuteConnectionProxyRequest
  - `async` boolean — When true, submits a GET request for asynchronous execution and returns a job handle instead of a synchronous upstream response.
  - `request` ConnectionProxyCall, required
    - `body` unknown
    - `headers` object — Additional request headers to send upstream. Headers listed in the connection's blockedRequestHeaders are rejected, and inherited auth headers cannot be overridden.
    - `method` string, required — HTTP method. Must be one of GET, POST, PUT, PATCH, DELETE.
    - `path` string, required — Relative upstream path. Query strings must be passed in request.query or request.rawQuery.
    - `query` object — Structured query parameters. Keys and values are URL-encoded before forwarding. Mutually exclusive with rawQuery.
    - `rawQuery` string — Exact query string fragment appended as-is after inherited query parameters. Do not include a leading '?'. Caller is responsible for encoding and syntax. Mutually exclusive with query.

## Response `200`

OK

- ExecuteConnectionProxyEnvelope
  - `data` ConnectionProxyResponse
    - `body` string — Upstream response body. If the upstream returned JSON, the body is returned as-is; otherwise it is returned as a string.
    - `contentType` string — Content-Type of the upstream response.
    - `headers` object, nullable — Response headers returned by the upstream service. Headers listed in blockedResponseHeaders are removed.
    - `jobId` string, uuid — Identifier for the async proxy job when async is true.
    - `jobStatus` 'created' | 'running' | 'done' | 'failed'
    - `jobUrl` string — Polling URL for the async proxy job when async is true.
    - `latencyMs` integer — End-to-end latency of the proxied request in milliseconds.
    - `proxyCallId` string, uuid — Identifier for this proxy call, suitable for correlating with audit logs.
    - `status` integer — HTTP status code returned by the upstream service for synchronous calls, or 202 when an async proxy job is accepted.
    - `truncated` boolean — True if the response body was truncated because it exceeded maxResponseBodyBytes.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `429` — Too Many Requests
- `500` — Internal Server Error
- `502` — Bad Gateway
- `504` — Gateway Timeout

---

[API](https://skmtc.net/polytomic/apis/polytomic-api.md) · [All operations](https://skmtc.net/polytomic/apis/polytomic-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/polytomic/polytomic-api/versions/5e9bcd4cfb2d/schema)