ClickStack: List Sources | ClickHouse Docs

GET/v1/organizations/{organizationId}/services/{serviceId}/clickstack/sources

This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future.

ClickStack: Retrieves a list of all sources for the authenticated team

Authorizations

Authorizationstringheaderrequired
Use key ID and key secret obtained in ClickHouse Cloud console: https://clickhouse.com/docs/cloud/manage/openapi

Path parameters

organizationIdstringrequired
ID of the organization that owns the service.

format: uuid
serviceIdstringrequired
ID of the ClickStack service.

format: uuid

Response

JSON

200

Successful response

JSON

statusoptionalnumber
HTTP status code.

Example: 200
requestIdoptionalstring
Unique id assigned to every request. UUIDv4

format: uuid
resultoptionalarray ofClickStackLogSourceorClickStackTraceSourceorClickStackMetricSourceorClickStackSessionSourceorClickStackPromqlSource
5 variants
One of the following:
ClickStackLogSource
View ClickStackLogSource schema →
29 properties
namestringrequired
Display name for the source.

Example: "Logs"
kindlogrequired
Source kind discriminator. Must be "log" for log sources.

Example: "log"
connectionstringrequired
ID of the ClickHouse connection used by this source.

Example: "507f1f77bcf86cd799439012"
fromobjectrequired
2 properties
databaseNamestringrequired
ClickHouse database name

Example: "otel"
tableNamestringrequired
ClickHouse table name

Example: "otel_logs"
defaultTableSelectExpressionstringrequired
Default columns selected in search results (this can be customized per search later)

Example: "Timestamp, ServiceName, SeverityText, Body"
timestampValueExpressionstringrequired
DateTime column or expression that is part of your table's primary key.

Example: "Timestamp"
idoptionalstring
Unique source ID. Server-generated; ignored if sent in create/update requests.

Example: "507f1f77bcf86cd799439011"
sectionoptionalstring
Optional grouping label used to organize sources in the source selector. Sources that share a section value are displayed together.

Example: "Billing"
disabledoptionalboolean | null
When true, the source is hidden from source selectors in the UI. Defaults to false.

Example: false
querySettingsoptionalarray ofobject
Optional ClickHouse query settings applied when querying this source.

2 properties
settingstringrequired
ClickHouse setting name

Example: "max_threads"
valuestringrequired
Setting value

Example: "4"
filterSettingsoptionalClickStackSourceFilterSettingsornull
2 variants
One of the following:
ClickStackSourceFilterSettings
null
serviceNameExpressionoptionalstring | null
Expression to extract the service name from log rows.

Example: "ServiceName"
serviceVersionExpressionoptionalstring | null
Expression identifying the running release of a service. Defaults to the OpenTelemetry service.version resource attribute when unset. Where services carry the release on different attributes, fall back across them with coalesce(nullIf(a, ''), nullIf(b, '')).

Example: "ResourceAttributes['service.version']"
severityTextExpressionoptionalstring | null
Expression to extract the severity/log level text.

Example: "SeverityText"
bodyExpressionoptionalstring | null
Expression to extract the log message body.

Example: "Body"
eventAttributesExpressionoptionalstring | null
Expression to extract event-level attributes.

Example: "LogAttributes"
resourceAttributesExpressionoptionalstring | null
Expression to extract resource-level attributes.

Example: "ResourceAttributes"
displayedTimestampValueExpressionoptionalstring | null
This DateTime column is used to display and order search results.

Example: "TimestampTime"
metricSourceIdoptionalstring | null
HyperDX Source for metrics associated with logs. Optional

Example: "507f1f77bcf86cd799439013"
traceSourceIdoptionalstring | null
HyperDX Source for traces associated with logs. Optional

Example: "507f1f77bcf86cd799439014"
traceIdExpressionoptionalstring | null
Expression to extract the trace ID for correlating logs with traces.

Example: "TraceId"
spanIdExpressionoptionalstring | null
Expression to extract the span ID for correlating logs with traces.

Example: "SpanId"
implicitColumnExpressionoptionalstring | null
Column used for full text search if no property is specified in a Lucene-based search. Typically the message body of a log.

Example: "Body"
knownColumnsListExpressionoptionalstring | null
For Distributed table sources whose target tables have non-matching column sets. A list of columns supported across all target tables, used instead of SELECT * when fetching full row data. Leave blank to select all columns.

Example: "Timestamp, Body, ServiceName"
useTextIndexForImplicitColumnoptionalautoorenabledordisabled
Controls whether lucene rendering uses ClickHouse text indices via hasAllTokens() against the implicit column. "auto" detects a covering index at query time, "enabled" forces text index usage, "disabled" forces a LIKE/hasToken fallback.

Example: "auto"
highlightedTraceAttributeExpressionsoptionalarray ofobject
Expressions defining trace-level attributes which are displayed in the trace view for the selected trace.

3 properties
sqlExpressionstringrequired
SQL expression for the attribute

Example: "SpanAttributes['http.status_code']"
luceneExpressionoptionalstring | null
An optional, Lucene version of the sqlExpression expression. If provided, it is used when searching for this attribute value.

Example: "http.status_code"
aliasoptionalstring | null
Optional alias for the attribute

Example: "HTTP Status Code"
highlightedRowAttributeExpressionsoptionalarray ofobject
Expressions defining row-level attributes which are displayed in the row side panel for the selected row.

3 properties
sqlExpressionstringrequired
SQL expression for the attribute

Example: "SpanAttributes['http.status_code']"
luceneExpressionoptionalstring | null
An optional, Lucene version of the sqlExpression expression. If provided, it is used when searching for this attribute value.

Example: "http.status_code"
aliasoptionalstring | null
Optional alias for the attribute

Example: "HTTP Status Code"
materializedViewsoptionalarray ofobject
Configure materialized views for query optimization. These pre-aggregated views can significantly improve query performance on aggregation queries.

7 properties
databaseNamestringrequired
Database name for the materialized view

Example: "otel"
tableNamestringrequired
Table name for the materialized view

Example: "otel_logs_mv_5m"
dimensionColumnsstringrequired
Columns which are not pre-aggregated in the materialized view and can be used for filtering and grouping.

Example: "ServiceName, SeverityText"
minGranularitystringrequired
The granularity of the timestamp column: a positive integer followed by a unit (s, m, h, d). Common values: 1s, 15s, 30s, 1m, 5m, 15m, 30m, 1h, 2h, 6h, 12h, 1d, 2d, 7d, 30d.

Example: "5m"
timestampColumnstringrequired
Timestamp column name

Example: "Timestamp"
aggregatedColumnsarray ofobjectrequired
Columns which are pre-aggregated by the materialized view

3 properties
aggFnstringrequired
Aggregation function (e.g., count, sum, avg)

Example: "sum"
mvColumnstringrequired
Materialized view column name

Example: "sum__Duration"
sourceColumnoptionalstring | null
Source column name

Example: "Duration"
minDateoptionalstring | null
(Optional) The earliest date and time for which the materialized view contains data. If not provided, then HyperDX will assume that the materialized view contains data for all dates for which the source table contains data.

format: date-time
Example: "2025-01-01T00:00:00Z"
metadataMaterializedViewsoptionalClickStackLogSourceMetadataMaterializedViewsornull
2 variants
One of the following:
ClickStackLogSourceMetadataMaterializedViews
null
ClickStackTraceSource
View ClickStackTraceSource schema →
35 properties
namestringrequired
Display name for the source.

Example: "Traces"
kindtracerequired
Source kind discriminator. Must be "trace" for trace sources.

Example: "trace"
connectionstringrequired
ID of the ClickHouse connection used by this source.

Example: "507f1f77bcf86cd799439012"
fromobjectrequired
2 properties
databaseNamestringrequired
ClickHouse database name

Example: "otel"
tableNamestringrequired
ClickHouse table name

Example: "otel_logs"
defaultTableSelectExpressionstringrequired
Default columns selected in search results (this can be customized per search later)

Example: "Timestamp, SpanName, ServiceName, Duration"
timestampValueExpressionstringrequired
DateTime column or expression defines the start of the span

Example: "Timestamp"
durationExpressionstringrequired
Expression to extract span duration.

Example: "Duration"
durationPrecisionintegerrequired
Number of decimal digits in the duration value (e.g., 3 for milliseconds, 6 for microseconds, 9 for nanoseconds).

traceIdExpressionstringrequired
Expression to extract the trace ID.

Example: "TraceId"
spanIdExpressionstringrequired
Expression to extract the span ID.

Example: "SpanId"
parentSpanIdExpressionstringrequired
Expression to extract the parent span ID.

Example: "ParentSpanId"
spanNameExpressionstringrequired
Expression to extract the span name.

Example: "SpanName"
spanKindExpressionstringrequired
Expression to extract the span kind (e.g., client, server, internal).

Example: "SpanKind"
idoptionalstring
Unique source ID. Server-generated; ignored if sent in create/update requests.

Example: "507f1f77bcf86cd799439021"
sectionoptionalstring
Optional grouping label used to organize sources in the source selector. Sources that share a section value are displayed together.

Example: "Billing"
disabledoptionalboolean | null
When true, the source is hidden from source selectors in the UI. Defaults to false.

Example: false
querySettingsoptionalarray ofobject
Optional ClickHouse query settings applied when querying this source.

2 properties
settingstringrequired
ClickHouse setting name

Example: "max_threads"
valuestringrequired
Setting value

Example: "4"
filterSettingsoptionalClickStackSourceFilterSettingsornull
2 variants
One of the following:
ClickStackSourceFilterSettings
null
logSourceIdoptionalstring | null
HyperDX Source for logs associated with traces. Optional

Example: "507f1f77bcf86cd799439011"
sessionSourceIdoptionalstring | null
HyperDX Source for sessions associated with traces. Optional

Example: "507f1f77bcf86cd799439031"
metricSourceIdoptionalstring | null
HyperDX Source for metrics associated with traces. Optional

Example: "507f1f77bcf86cd799439041"
statusCodeExpressionoptionalstring | null
Expression to extract the span status code.

Example: "StatusCode"
statusMessageExpressionoptionalstring | null
Expression to extract the span status message.

Example: "StatusMessage"
serviceNameExpressionoptionalstring | null
Expression to extract the service name from trace rows.

Example: "ServiceName"
serviceVersionExpressionoptionalstring | null
Expression identifying the running release of a service. Defaults to the OpenTelemetry service.version resource attribute when unset. Where services carry the release on different attributes, fall back across them with coalesce(nullIf(a, ''), nullIf(b, '')).

Example: "ResourceAttributes['service.version']"
resourceAttributesExpressionoptionalstring | null
Expression to extract resource-level attributes.

Example: "ResourceAttributes"
eventAttributesExpressionoptionalstring | null
Expression to extract event-level attributes.

Example: "SpanAttributes"
spanEventsValueExpressionoptionalstring | null
Expression to extract span events. Used to capture events associated with spans. Expected to be Nested ( Timestamp DateTime64(9), Name LowCardinality(String), Attributes Map(LowCardinality(String), String)

Example: "Events"
implicitColumnExpressionoptionalstring | null
Column used for full text search if no property is specified in a Lucene-based search. Typically the message body of a log.

Example: "SpanName"
knownColumnsListExpressionoptionalstring | null
For Distributed table sources whose target tables have non-matching column sets. A list of columns supported across all target tables, used instead of SELECT * when fetching full row data. Leave blank to select all columns.

Example: "Timestamp, Body, ServiceName"
useTextIndexForImplicitColumnoptionalautoorenabledordisabled
Controls whether lucene rendering uses ClickHouse text indices via hasAllTokens() against the implicit column. "auto" detects a covering index at query time, "enabled" forces text index usage, "disabled" forces a LIKE/hasToken fallback.

Example: "auto"
highlightedTraceAttributeExpressionsoptionalarray ofobject
Expressions defining trace-level attributes which are displayed in the trace view for the selected trace.

3 properties
sqlExpressionstringrequired
SQL expression for the attribute

Example: "SpanAttributes['http.status_code']"
luceneExpressionoptionalstring | null
An optional, Lucene version of the sqlExpression expression. If provided, it is used when searching for this attribute value.

Example: "http.status_code"
aliasoptionalstring | null
Optional alias for the attribute

Example: "HTTP Status Code"
highlightedRowAttributeExpressionsoptionalarray ofobject
Expressions defining row-level attributes which are displayed in the row side panel for the selected row

3 properties
sqlExpressionstringrequired
SQL expression for the attribute

Example: "SpanAttributes['http.status_code']"
luceneExpressionoptionalstring | null
An optional, Lucene version of the sqlExpression expression. If provided, it is used when searching for this attribute value.

Example: "http.status_code"
aliasoptionalstring | null
Optional alias for the attribute

Example: "HTTP Status Code"
materializedViewsoptionalarray ofobject
Configure materialized views for query optimization. These pre-aggregated views can significantly improve query performance on aggregation queries.

7 properties
databaseNamestringrequired
Database name for the materialized view

Example: "otel"
tableNamestringrequired
Table name for the materialized view

Example: "otel_logs_mv_5m"
dimensionColumnsstringrequired
Columns which are not pre-aggregated in the materialized view and can be used for filtering and grouping.

Example: "ServiceName, SeverityText"
minGranularitystringrequired
The granularity of the timestamp column: a positive integer followed by a unit (s, m, h, d). Common values: 1s, 15s, 30s, 1m, 5m, 15m, 30m, 1h, 2h, 6h, 12h, 1d, 2d, 7d, 30d.

Example: "5m"
timestampColumnstringrequired
Timestamp column name

Example: "Timestamp"
aggregatedColumnsarray ofobjectrequired
Columns which are pre-aggregated by the materialized view

3 properties
aggFnstringrequired
Aggregation function (e.g., count, sum, avg)

Example: "sum"
mvColumnstringrequired
Materialized view column name

Example: "sum__Duration"
sourceColumnoptionalstring | null
Source column name

Example: "Duration"
minDateoptionalstring | null
(Optional) The earliest date and time for which the materialized view contains data. If not provided, then HyperDX will assume that the materialized view contains data for all dates for which the source table contains data.

format: date-time
Example: "2025-01-01T00:00:00Z"
metadataMaterializedViewsoptionalClickStackTraceSourceMetadataMaterializedViewsornull
2 variants
One of the following:
ClickStackTraceSourceMetadataMaterializedViews
null
ClickStackMetricSource
View ClickStackMetricSource schema →
12 properties
namestringrequired
Display name for the source.

Example: "Metrics"
kindmetricrequired
Source kind discriminator. Must be "metric" for metric sources.

Example: "metric"
connectionstringrequired
ID of the ClickHouse connection used by this source.

Example: "507f1f77bcf86cd799439012"
fromobjectrequired
2 properties
databaseNamestringrequired
ClickHouse database name

Example: "otel"
tableNameoptionalstring | null
ClickHouse table name

Example: "otel_metrics_gauge"
metricTablesobjectrequired
5 properties
gaugeoptionalstring
Table containing gauge metrics data

Example: "otel_metrics_gauge"
histogramoptionalstring
Table containing histogram metrics data

Example: "otel_metrics_histogram"
sumoptionalstring
Table containing sum metrics data

Example: "otel_metrics_sum"
summaryoptionalstring
Table containing summary metrics data. Note - not yet fully supported by HyperDX

Example: "otel_metrics_summary"
exponential histogramoptionalstring
Table containing exponential histogram metrics data. Note - not yet fully supported by HyperDX

Example: "otel_metrics_exponential_histogram"
timestampValueExpressionstringrequired
DateTime column or expression that is part of your table's primary key.

Example: "TimeUnix"
resourceAttributesExpressionstringrequired
Column containing resource attributes for metrics

Example: "ResourceAttributes"
idoptionalstring
Unique source ID. Server-generated; ignored if sent in create/update requests.

Example: "507f1f77bcf86cd799439041"
sectionoptionalstring
Optional grouping label used to organize sources in the source selector. Sources that share a section value are displayed together.

Example: "Billing"
disabledoptionalboolean | null
When true, the source is hidden from source selectors in the UI. Defaults to false.

Example: false
querySettingsoptionalarray ofobject
Optional ClickHouse query settings applied when querying this source.

2 properties
settingstringrequired
ClickHouse setting name

Example: "max_threads"
valuestringrequired
Setting value

Example: "4"
logSourceIdoptionalstring | null
HyperDX Source for logs associated with metrics. Optional

Example: "507f1f77bcf86cd799439011"
ClickStackSessionSource
View ClickStackSessionSource schema →
10 properties
namestringrequired
Display name for the source.

Example: "Sessions"
kindsessionrequired
Source kind discriminator. Must be "session" for session sources.

Example: "session"
connectionstringrequired
ID of the ClickHouse connection used by this source.

Example: "507f1f77bcf86cd799439012"
fromobjectrequired
2 properties
databaseNamestringrequired
ClickHouse database name

Example: "otel"
tableNamestringrequired
ClickHouse table name

Example: "otel_logs"
traceSourceIdstringrequired
HyperDX Source for traces associated with sessions.

Example: "507f1f77bcf86cd799439021"
idoptionalstring
Unique source ID. Server-generated; ignored if sent in create/update requests.

Example: "507f1f77bcf86cd799439031"
sectionoptionalstring
Optional grouping label used to organize sources in the source selector. Sources that share a section value are displayed together.

Example: "Billing"
disabledoptionalboolean | null
When true, the source is hidden from source selectors in the UI. Defaults to false.

Example: false
querySettingsoptionalarray ofobject
Optional ClickHouse query settings applied when querying this source.

2 properties
settingstringrequired
ClickHouse setting name

Example: "max_threads"
valuestringrequired
Setting value

Example: "4"
timestampValueExpressionoptionalstring | null
DateTime column or expression that is part of your table's primary key.

Example: "TimestampTime"
ClickStackPromqlSource
View ClickStackPromqlSource schema →
9 properties
namestringrequired
Display name for the source.

Example: "Prometheus Metrics"
kindpromqlrequired
Source kind discriminator. Must be "promql" for PromQL sources.

Example: "promql"
connectionstringrequired
ID of the connection used by this source. Should reference a Prometheus-compatible connection.

Example: "507f1f77bcf86cd799439012"
fromobjectrequired
2 properties
databaseNamestringrequired
ClickHouse database name

Example: "otel"
tableNamestringrequired
ClickHouse table name

Example: "otel_logs"
timestampValueExpressionstringrequired
Required by the API for all source kinds; not used when querying a Prometheus endpoint.

Example: "timestamp"
idoptionalstring
Unique source ID. Server-generated; ignored if sent in create/update requests.

Example: "507f1f77bcf86cd799439051"
sectionoptionalstring
Optional grouping label used to organize sources in the source selector. Sources that share a section value are displayed together.

Example: "Billing"
disabledoptionalboolean | null
When true, the source is hidden from source selectors in the UI. Defaults to false.

Example: false
querySettingsoptionalarray ofobject
Optional ClickHouse query settings applied when querying this source.

2 properties
settingstringrequired
ClickHouse setting name

Example: "max_threads"
valuestringrequired
Setting value

Example: "4"

ClickStack: List Sources

curl --request GET \
  --url https://api.clickhouse.cloud/v1/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/services/497f6eca-6276-4993-bfeb-53cbbbba6f08/clickstack/sources \
  --header 'Authorization: Basic <token>'

const url = 'https://api.clickhouse.cloud/v1/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/services/497f6eca-6276-4993-bfeb-53cbbbba6f08/clickstack/sources';
const options = {method: 'GET', headers: {Authorization: 'Basic <token>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

import requests

url = "https://api.clickhouse.cloud/v1/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/services/497f6eca-6276-4993-bfeb-53cbbbba6f08/clickstack/sources"

headers = {"Authorization": "Basic <token>"}

response = requests.get(url, headers=headers)

print(response.text)

Response example

{
  "status": 200,
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "result": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "Logs",
      "section": "Billing",
      "disabled": false,
      "kind": "log",
      "connection": "507f1f77bcf86cd799439012",
      "from": {
        "databaseName": "otel",
        "tableName": "otel_logs"
      },
      "querySettings": [
        {
          "setting": "max_threads",
          "value": "4"
        }
      ],
      "filterSettings": {
        "databaseName": "default",
        "tableName": "otel_logs",
        "columns": [
          {
            "name": "ServiceName",
            "label": "Service Name",
            "valueExpression": "lower(service_name)",
            "allowAll": false
          }
        ]
      },
      "defaultTableSelectExpression": "Timestamp, ServiceName, SeverityText, Body",
      "timestampValueExpression": "Timestamp",
      "serviceNameExpression": "ServiceName",
      "serviceVersionExpression": "ResourceAttributes['service.version']",
      "severityTextExpression": "SeverityText",
      "bodyExpression": "Body",
      "eventAttributesExpression": "LogAttributes",
      "resourceAttributesExpression": "ResourceAttributes",
      "displayedTimestampValueExpression": "TimestampTime",
      "metricSourceId": "507f1f77bcf86cd799439013",
      "traceSourceId": "507f1f77bcf86cd799439014",
      "traceIdExpression": "TraceId",
      "spanIdExpression": "SpanId",
      "implicitColumnExpression": "Body",
      "knownColumnsListExpression": "Timestamp, Body, ServiceName",
      "useTextIndexForImplicitColumn": "auto",
      "highlightedTraceAttributeExpressions": [
        {
          "sqlExpression": "SpanAttributes['http.status_code']",
          "luceneExpression": "http.status_code",
          "alias": "HTTP Status Code"
        }
      ],
      "highlightedRowAttributeExpressions": [
        {
          "sqlExpression": "SpanAttributes['http.status_code']",
          "luceneExpression": "http.status_code",
          "alias": "HTTP Status Code"
        }
      ],
      "materializedViews": [
        {
          "databaseName": "otel",
          "tableName": "otel_logs_mv_5m",
          "dimensionColumns": "ServiceName, SeverityText",
          "minGranularity": "5m",
          "minDate": "2025-01-01T00:00:00Z",
          "timestampColumn": "Timestamp",
          "aggregatedColumns": [
            {
              "sourceColumn": "Duration",
              "aggFn": "sum",
              "mvColumn": "sum__Duration"
            }
          ]
        }
      ],
      "metadataMaterializedViews": {
        "keyRollupTable": "otel_logs_key_rollup_15m",
        "kvRollupTable": "otel_logs_kv_rollup_15m",
        "granularity": "15m"
      }
    }
  ]
}

{
  "status": 400,
  "error": "string",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6"
}

{
  "status": 500,
  "error": "string",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6"
}