Get a single connection

Retrieves the details of a specific ClickHouse connection.

GET https://telemetry.betterstack.com/api/v1/connections/{id}

URL parameters

required string

The ID of the connection to retrieve.

Headers

Authorization

required string

Bearer $TOKEN

200

The details of the specified connection.

Response body

{
  "data": {
    "id": "42510",
    "type": "connection",
    "attributes": {
      "id": 42510,
      "client_type": "clickhouse",
      "note": "My testing connection",
      "created_at": "2025-05-23T13:16:31.419Z",
      "valid_until": null,
      "host": "eu-nbg-2-connect.betterstackdata.com",
      "port": 443,
      "username": "u5LJyB8U1UFmw4fRFrnu74Kh1G4Nfnh6s",
      "data_region": "eu-nbg-2",
      "ip_allowlist": [],
      "team_ids": [
        1234
      ],
      "team_names": [
        "My Team"
      ],
      "created_by": {
        "id": 456789,
        "email": "my@email.com"
      },
      "sample_query": "curl -u u5LJyB8U1UFmw4fRtXnu74Kh1G4Nfnh6s:INSERT_PASSWORD -H 'Content-type: plain/text' -X POST 'https://eu-nbg-2-connect.betterstackdata.com?output_format_pretty_row_numbers=0' -d \"SELECT query_collection || '_' || type AS named_collection, multiIf( type = 'logs', 'SELECT dt, raw FROM remote(' || query_collection || '_logs) LIMIT 10 UNION ALL SELECT dt, raw FROM s3Cluster(primary, ' || query_collection || '_s3) WHERE _row_type = 1 LIMIT 10', type = 'spans', 'SELECT dt, raw FROM remote(' || query_collection || '_spans) LIMIT 10 UNION ALL SELECT dt, raw FROM s3Cluster(primary, ' || query_collection || '_s3) WHERE _row_type = 3 LIMIT 10', type = 'metrics', 'SELECT toStartOfHour(dt) AS time, countMerge(events_count) FROM remote(' || query_collection || '_metrics) GROUP BY time ORDER BY time DESC LIMIT 10', null ) AS query_with FROM VALUES('query_collection String, type String', ('t1234_local_kubernetes', 'logs'), ('t1234_local_kubernetes', 'spans'), ('t1234_local_kubernetes', 'metrics'), ('t1234_testing_syslog', 'logs'),  ('t1234_testing_syslog', 'metrics')) ORDER BY named_collection FORMAT Pretty\"",
      "data_sources": [
        {
          "source_name": "Local Kubernetes",
          "source_id": 1234,
          "team_name": "My Team",
          "connection_url": "https://eu-nbg-2-connect.betterstackdata.com",
          "data_sources": [
            "remote(t1234_local_kubernetes_logs)",
            "remote(t1234_local_kubernetes_spans)",
            "remote(t1234_local_kubernetes_metrics)",
            "s3Cluster(primary, t1234_local_kubernetes_s3)"
          ]
        },
        {
          "source_name": "Testing syslog",
          "source_id": 1376836,
          "team_name": "My Team",
          "connection_url": "https://eu-nbg-2-connect.betterstackdata.com",
          "data_sources": [
            "remote(t1234_testing_syslog_logs)",
            "remote(t1234_testing_syslog_metrics)",
            "s3Cluster(primary, t1234_testing_syslog_s3)"
          ]
        }
      ]
    }
  }
}

404

Resource with the provided ID was not found.

Response body

{
  "errors": "Resource with the provided ID was not found"
}

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.

attributes.sample_query

string

A sample cURL command that queries the connection, with INSERT_PASSWORD in place of the password.

attributes.data_sources

array

The sources the connection can query, one object per source.

attributes.data_sources.source_name

string

The name of the source.

attributes.data_sources.source_id

integer

The ID of the source.

attributes.data_sources.team_name

string

The name of the team that owns the source.

attributes.data_sources.connection_url

string

The URL to query the source's data through.

attributes.data_sources.data_sources

array

The names of the source's tables the connection can query.

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/123 \
  --header "Authorization: Bearer $TOKEN"

List all connections

Create a connection

Explore documentation

Get a single connection

Example cURL

Please accept cookies