Get Connection

GET

https://app.polytomic.com/api/connections/:id

GET

/api/connections/:id

curl https://app.polytomic.com/api/connections/248df4b7-aa70-47b8-a036-33ac447e668d \
     -H "Authorization: Bearer <token>"

{
  "data": {
    "api_calls_last_24_hours": 2021,
    "configuration": {
      "database": "example",
      "hostname": "postgres.example.com",
      "password": "********",
      "port": 5432,
      "username": "user"
    },
    "created_at": "2024-01-15T09:30:00Z",
    "created_by": {
      "id": "12345678-1234-1234-1234-123456789012",
      "name": "John Doe",
      "type": "user"
    },
    "id": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "name": "My Postgres Connection",
    "organization_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "parent_connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "policies": [
      "248df4b7-aa70-47b8-a036-33ac447e668d"
    ],
    "rate_limit": {
      "currently_limited": true,
      "expires_at": "2024-01-15T09:30:00Z",
      "limited_since": "2024-01-15T09:30:00Z"
    },
    "saved": true,
    "status": "healthy",
    "status_error": "error message",
    "type": {
      "id": "postgresql",
      "logo_dark_url": "https://connect-assets.polytomic.com/logos/dark/postgresql.svg",
      "logo_url": "https://connect-assets.polytomic.com/logos/postgresql.svg",
      "name": "PostgreSQL",
      "operations": [
        "bulksyncsource"
      ]
    },
    "updated_at": "2024-01-15T09:30:00Z",
    "updated_by": {
      "id": "12345678-1234-1234-1234-123456789012",
      "name": "John Doe",
      "type": "user"
    }
  }
}

Returns a single connection by ID, with sensitive fields redacted.

To inspect the schemas available on this connection, trigger a refresh with POST /api/connections/{id}/schemas/refresh and track progress via GET /api/connections/{id}/schemas/status.

Observed rate limits

You can use rate_limit to inspect observed rate limiting separately from Connection health. A Connection can be healthy while Polytomic has an active rate-limit marker. Shared Connections combine observations recorded for their own ID and their root Connection. Observations recorded only for another shared copy are not included.

When these observed periods overlap or touch, limited_since reflects the start of the continuous period and expires_at reflects its latest expiry. An expired period separated from the active period by a gap does not extend that start.

⚠️ Observation, not a capacity guarantee

An active marker does not mean every endpoint or sync is blocked. No active marker does not guarantee that the upstream service has capacity. The marker expiry can be extended and is not a promised provider reset or exact retry time.

If any required lookup is unavailable, rate_limit is null. This does not change status or status_error, and the Connection response is still returned.

Returns a single connection by ID, with sensitive fields redacted. To inspect the schemas available on this connection, trigger a refresh with [`POST /api/connections/{id}/schemas/refresh`](../../../api-reference/schemas/refresh) and track progress via [`GET /api/connections/{id}/schemas/status`](../../../api-reference/schemas/get-status). ## Observed rate limits You can use `rate_limit` to inspect observed rate limiting separately from Connection health. A Connection can be healthy while Polytomic has an active rate-limit marker. Shared Connections combine observations recorded for their own ID and their root Connection. Observations recorded only for another shared copy are not included. When these observed periods overlap or touch, `limited_since` reflects the start of the continuous period and `expires_at` reflects its latest expiry. An expired period separated from the active period by a gap does not extend that start. > ⚠️ Observation, not a capacity guarantee > > An active marker does not mean every endpoint or sync is blocked. No active > marker does not guarantee that the upstream service has capacity. The marker > expiry can be extended and is not a promised provider reset or exact retry time. If any required lookup is unavailable, `rate_limit` is `null`. This does not change `status` or `status_error`, and the Connection response is still returned.

Authentication

AuthorizationBearer

Bearer user API key

AuthorizationBasic

Basic organization-scoped API key

Path parameters

idstringRequiredformat: "uuid"

Response

dataobjectOptional

Errors

404

Not Found Error

500

Internal Server Error

Observed rate limits

Authentication

Path parameters

Headers

Response

Errors

Observed rate limits