List all connections

Returns a paginated list of ClickHouse connections. For extra details, such as individual data sources, see Get a single connection API.

GET https://telemetry.betterstack.com/api/v1/connections

Query parameters

page

integer

Page number for pagination

per_page

integer

Number of items per page (default: 50, max: 250)

Headers

Authorization

required string

Bearer $TOKEN

200

A paginated list of connections.

Response body

{
  "data": [
    {
      "id": "43700",
      "type": "connection",
      "attributes": {
        "id": 43700,
        "client_type": "clickhouse",
        "note": "My testing connection",
        "created_at": "2025-10-18T10:00:44.890Z",
        "valid_until": null,
        "host": "eu-nbg-2-connect.betterstackdata.com",
        "port": 443,
        "username": "uodjialjQXSPe66TePguwdE72Jjvn9DNy",
        "data_region": "eu-nbg-2",
        "ip_allowlist": [],
        "team_ids": [
          1234
        ],
        "team_names": [
          "My Team"
        ],
        "created_by": {
          "id": 456789,
          "email": "my@email.com"
        }
      }
    }
  ],
  "pagination": {
    "first": "https://telemetry.betterstack.com/api/v1/connections?page=1",
    "last": "https://telemetry.betterstack.com/api/v1/connections?page=1",
    "prev": null,
    "next": null
  }
}

Response attributes

string

The ID of the connection.

type

string

The resource type, always connection.

attributes.id

integer

The ID of the connection as an integer.

attributes.client_type

string

The client the connection is for, clickhouse or grafana.

attributes.note

string or null

The note describing the connection, or null when none is set.

attributes.created_at

string

When the connection was created, as an ISO 8601 date-time in UTC.

attributes.valid_until

string or null

When the connection expires, as an ISO 8601 date-time in UTC, or null when it never expires.

attributes.host

string

The host to connect to.

attributes.port

integer

The port to connect to, always 443.

attributes.username

string

The username to connect with, while the password is returned only when the connection is created.

attributes.data_region

string or null

The data region the connection is pinned to, or null when the connection spans every region its teams use.

attributes.ip_allowlist

array

The IP addresses and CIDR ranges allowed to use the connection.

attributes.team_ids

array

The IDs of the teams whose data the connection can query.

attributes.team_names

array

The names of the teams whose data the connection can query.

attributes.created_by

object or null

The user who created the connection, or null when it was created through the API.

attributes.created_by.id

integer

The ID of the user who created the connection.

attributes.created_by.email

string

The email address of the user who created the connection.

pagination.first

string

URL of the first page. Read more about pagination.

pagination.last

string

URL of the last page.

pagination.prev

string or null

URL of the previous page, or null on the first page.

pagination.next

string or null

URL of the next page, or null on the last page.

This API requires a global API token for authentication, not a team-specific token. Include the token in the Authorization header.

Example cURL

Example

Copied!

curl --request GET \
  --url https://telemetry.betterstack.com/api/v1/connections \
  --header "Authorization: Bearer $TOKEN"

Remove an alert

Get a single connection

Explore documentation

List all connections

Example cURL

Please accept cookies