---
title: "List connections"
method: GET
path: "/api/v1/connections"
tags: ["connections"]
---

# List connections

`GET /api/v1/connections`

List warehouse connections for the client.

Filter connections by approval status using the `status` query parameter:
- `approved` (default): Only approved connections (is_pending_approval=false)
- `pending`: Only connections awaiting PR approval (is_pending_approval=true)
- `all`: All connections regardless of approval status

Pending connections include their approval PR URLs when available.
Returns empty list if GitHub is not configured.

RLS: Filtered to current client (DualClientRLSDB).

## Query parameters

- `status` 'approved' | 'pending' | 'all'

## Response `200`

Successful Response

- ConnectionResponse[]
  - `approval_pr_url` string, nullable — GitHub PR URL for approving the connection (None if already approved)
  - `created_at` string, date-time, required — Creation timestamp
  - `credential_id` string, uuid, required — Credential ID
  - `databases` ConnectionDatabaseInfo[], required — Databases in this connection
    - `database_object_name` string, required — Actual name of the database in the warehouse
    - `description` string, nullable — Database description
    - `id` string, uuid, required — Database ID
    - `label` string, nullable — Human-readable label
    - `name` string, required — Database name
    - `schemas` SchemaInfo[], required — Schemas in this database
      - `database_object_name` string, required — Actual name of the schema in the warehouse
      - `description` string, nullable — Schema description
      - `id` string, uuid, required — Schema ID
      - `label` string, nullable — Human-readable label
      - `name` string, required — Schema name
    - `timezone` string, nullable — Timezone for the database
  - `description` string, nullable — Connection description
  - `id` string, uuid, required — Connection ID
  - `is_pending_approval` boolean — True if this connection is awaiting PR approval
  - `label` string, nullable — Human-readable label
  - `name` string, required — Connection name
  - `query_timeout` integer, nullable — Query timeout in seconds
  - `query_timezone_conversion` string, nullable — Timezone conversion mode (do_not_convert, convert_to_utc)
  - `updated_at` string, date-time, required — Last update timestamp
  - `warehouse_metadata` union, required — Warehouse-specific configuration
    - SnowflakeMetadata
      - `auth_method` 'username_password' | 'key_pair', required — Authentication method
      - `role` string, required — Snowflake role
      - `snowflake_account_id` string, required — Snowflake account identifier
      - `warehouse` string, required — Snowflake compute warehouse name
      - `warehouse_type` 'snowflake', required
    - PostgresqlMetadata
      - `host` string, required — Database host address
      - `port` integer, required — Database port (default: 5432)
      - `warehouse_type` 'postgresql', required
    - DatabricksMetadata
      - `http_path` string, required — Databricks SQL warehouse HTTP path
      - `server_hostname` string, required — Databricks server hostname
      - `warehouse_type` 'databricks', required
    - ClickhouseMetadata
      - `host` string, required — ClickHouse host address
      - `port` integer, required — ClickHouse port (default: 8443)
      - `warehouse_type` 'clickhouse', required
    - MssqlMetadata
      - `host` string, required — SQL Server host address
      - `port` integer, required — SQL Server port (default: 1433)
      - `warehouse_type` 'mssql', required
  - `warehouse_type` string, required — Warehouse type (snowflake, postgresql, etc.)

## Other responses

- `401` — Unauthorized
- `422` — Validation Error

## Changes

- **2026-02-26** `bef1f3e205dd` — 2 breaking
  - response property `errors` list-of-types was widened by adding types `array` to media type `application/json` of response `401`
  - response property `errors` list-of-types was widened by adding types `array` to media type `application/json` of response `422`
- **2026-02-08** `91ea1d9f6c07` — 1 breaking, 2 warning, 8 info
  - added `#/components/schemas/PostgresqlMetadata, #/components/schemas/ClickhouseMetadata, #/components/schemas/MssqlMetadata` to the `items/warehouse_metadata` response property `oneOf` list for the response status `200`
  - removed the optional property `items/database_timezone` from the response with the `200` status
  - removed the optional property `items/sync_id` from the response with the `200` status
  - added the new optional `query` request parameter `status`
  - …7 more
- **2026-01-29** `d2a2a2d0775e` — 2 info
  - added the required property `items/databases/items/database_object_name` to the response with the `200` status
  - added the required property `items/databases/items/schemas/items/database_object_name` to the response with the `200` status
- …earlier changes not shown

[Full history](https://skmtc.dev/kater-ai/apis/kater-api/changes/api/v1/connections/get.md)

---

[API](https://skmtc.dev/kater-ai/apis/kater-api.md) · [All operations](https://skmtc.dev/kater-ai/apis/kater-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/kater-ai/kater-api/revisions/6a140b82e07c/schema)