Explore documentation
  1. Welcome to Telemetry 👋
  2. Quick start guide
  3. Wide events vs. time series
  4. Ingesting data
    1. Better Stack collector
    2. Vector
    3. OpenTelemetry
    4. Ingesting via HTTP API
    5. Ingesting metrics
    6. Ingesting logs
    7. Migrating to Better Stack
  5. Using the product
    1. Transforming ingested data
    2. Querying data
    3. Tracing
    4. Alerts
  6. Telemetry API
    1. Getting an API token
    2. Sources
    3. Metrics API
    4. Connections API
      1. List all connections GET
      2. Get a single connection GET
      3. Create a connection POST
      4. Remove a connection DELETE
    5. Query API ↗
  7. Alternative to
    1. Lightstep

Create a connection

Creates a new ClickHouse connection.

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

Headers

Authorization
required string

Bearer $TOKEN

Content-Type
required string

application/json

Body parameters

client_type
required string

Type of client connection. Currently only clickhouse is supported.

team_names
array

Array of team names to associate with the connection. Connections are organization-wide, but can be scoped to specific teams for data access control. Only one of team_names or team_ids should be provided.

team_ids
array

Array of team IDs to associate with the connection. Connections are organization-wide, but can be scoped to specific teams for data access control. Only one of team_names or team_ids should be provided.

data_region
string

Data region or private cluster name to create the source in.
Permitted values for most plans are: us_east, us_west, germany, singapore.

ip_allowlist
array

Array of IP addresses or CIDR ranges that are allowed to use this connection.

valid_until
string

ISO 8601 timestamp when the connection expires.

note
string

A descriptive note for the connection.

201

The newly created connection, including its password.

Response body

{
  "data": {
    "id": "44498",
    "type": "connection",
    "attributes": {
      "id": 44498,
      "client_type": "clickhouse",
      "note": "Production connection for analytics",
      "created_at": "2025-11-07T13:20:55.652Z",
      "valid_until": "2025-12-02T00:00:00.000Z",
      "host": "eu-nbg-2-connect.betterstackdata.com",
      "port": 443,
      "username": "urKyY9Y1ojWOAjtmAZ3hswsdfvedCRXir",
      "password": "31ctySUgUnSuuppbroGLp66kBdB7ngHzoipm3yEEp6TX8kT77E7EDUsHnDRWoIWC",
      "data_region": "eu-nbg-2",
      "ip_allowlist": [
        "192.168.1.0/24",
        "10.0.0.1"
      ],
      "team_ids": [
        1234
      ],
      "team_names": [
        "My Team"
      ],
      "created_by": null,
      "sample_query": "curl -u urKyY9Y1ojWOAjtmAZ3hswsdfvedCRXir:31ctySUgUnSuuppbroGLp66kBdB7ngHzoipm3yEEp6TX8kT77E7EDUsHnDRWoIWC -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_application_example_2', 'logs'), ('t1234_application_example_2', 'metrics')) ORDER BY named_collection FORMAT Pretty\"",
      "data_sources": [
        {
          "source_name": "Application example",
          "source_id": 1325114,
          "team_name": "My Team",
          "data_sources": [
            "remote(t1234_application_example_2_logs)",
            "remote(t1234_application_example_2_metrics)",
            "s3Cluster(primary, t1234_application_example_2_s3)"
          ]
        }
      ]
    }
  }
}
422

Validation failed due to invalid parameters.

Response body

{
  "errors": "Cannot specify both team_names and team_ids"
}

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

The password is only returned in the creation response and cannot be retrieved later. Store it securely.

Example cURL

Example
curl --request POST \
  --url https://telemetry.betterstack.com/api/v1/connections \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "client_type": "clickhouse",
    "team_names": ["My Team"],
    "data_region": "germany",
    "ip_allowlist": ["192.168.1.0/24", "10.0.0.1"],
    "valid_until": "2025-12-02T00:00:00Z",
    "note": "Production connection for analytics"
  }'

Previous article

Get a single connection

Next article

Remove a connection