/v1/organizations/{organizationId}/services/{serviceId}/clickstack/sources/{clickStackSourceId}This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future.
ClickStack: Retrieves a specific source by ID
Permission
The API key must have the control-plane:service:manage-clickstack-api permission.
Authorizations
- AuthorizationstringheaderrequiredUse key ID and key secret obtained in ClickHouse Cloud console: https://clickhouse.com/docs/cloud/manage/openapi
Path parameters
Response
200
Successful response
- resultoptionalClickStackLogSourceorClickStackTraceSourceorClickStackMetricSourceorClickStackSessionSourceorClickStackPromqlSource
5 variants
One of the following:
- ClickStackLogSource{ … }
33 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" - fromobject{ … }required
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" - severityNumberExpressionoptionalstring | null
Expression for the numeric OpenTelemetry SeverityNumber (1-24).
Example: "SeverityNumber" - bodyExpressionoptionalstring | null
Expression to extract the log message body.
Example: "Body" - eventNameExpressionoptionalstring | null
Expression for the OpenTelemetry log EventName.
Example: "EventName" - 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" - orderByExpressionoptionalstring
Custom ORDER BY expression that overrides the default ordering. Leave empty to use the auto-detected default.
Example: "Timestamp DESC" - 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" - rowKeyExpressionoptionalstring | null
Comma-separated expressions that together identify one row, e.g. the partition key, primary key, _block_number and _block_offset. When set, row details are looked up by these columns only. Leave blank to detect keys from table metadata.
Example: "toDate(Timestamp), ServiceName, Timestamp, _block_number, _block_offset" - 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 ofobject{ … }required
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-timeExample: "2025-01-01T00:00:00Z"
- metadataMaterializedViewsoptionalClickStackLogSourceMetadataMaterializedViewsornull
2 variants
One of the following:
- ClickStackLogSourceMetadataMaterializedViews
- null
- ClickStackTraceSource{ … }
40 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" - fromobject{ … }required
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']" - sampleRateExpressionoptionalstring
Column or expression for upstream sampling weight (1/N). When set, aggregations (count, avg, sum, quantile) are corrected for sampling. Percentiles use quantileTDigestWeighted, which is an approximation. Leave empty if spans are not sampled.
Example: "SampleRate" - 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" - spanLinksValueExpressionoptionalstring
Expression to extract span links. Used to capture links from a span to spans in other traces. Expected to be Nested ( TraceId String, SpanId String, TraceState String, Attributes Map(LowCardinality(String), String) )
Example: "Links" - 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" - rowKeyExpressionoptionalstring | null
Comma-separated expressions that together identify one row, e.g. the partition key, primary key, _block_number and _block_offset. When set, row details are looked up by these columns only. Leave blank to detect keys from table metadata.
Example: "toDate(Timestamp), SpanName, Timestamp, _block_number, _block_offset" - 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"
- displayedTimestampValueExpressionoptionalstring
This DateTime column is used to display and order search results.
Example: "Timestamp" - orderByExpressionoptionalstring
Custom ORDER BY expression that overrides the default ordering. Leave empty to use the auto-detected default.
Example: "Timestamp DESC" - 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 ofobject{ … }required
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-timeExample: "2025-01-01T00:00:00Z"
- metadataMaterializedViewsoptionalClickStackTraceSourceMetadataMaterializedViewsornull
2 variants
One of the following:
- ClickStackTraceSourceMetadataMaterializedViews
- null
- ClickStackMetricSource{ … }
13 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" - fromobject{ … }required
2 properties
- databaseNamestringrequired
ClickHouse database name
Example: "otel" - tableNameoptionalstring | null
ClickHouse table name
Example: "otel_metrics_gauge"
- metricTablesobject{ … }required
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" - minAutoGranularityoptionalstring
Floor for the auto-inferred chart granularity. Set it to the scrape/report interval of the metrics so a short time range does not produce buckets smaller than that interval (sparse, steppy series). Only constrains "Auto" granularity; an explicit granularity picked on a tile is never overridden. Omit for no minimum. Uses the SQL interval format (a positive integer followed by second, minute, hour, or day), not the short form of the materialized view granularity fields.
Example: "1 minute"
- ClickStackSessionSource{ … }
11 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" - fromobject{ … }required
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" - resourceAttributesExpressionoptionalstring
Expression to extract resource-level attributes.
Example: "ResourceAttributes"
- ClickStackPromqlSource{ … }
11 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. Either a ClickHouse connection holding the TimeSeries table, or a Prometheus-compatible connection.
Example: "507f1f77bcf86cd799439012" - fromobject{ … }required
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 by PromQL queries.
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"
- minAutoGranularityoptionalstring
Floor for the auto-inferred chart granularity, and the scrape interval that
$__rate_intervalis computed from. Set it to the Prometheus scrape interval so a short time range does not produce buckets smaller than that interval. Only constrains "Auto" granularity; an explicit granularity picked on a tile is never overridden. Omit for no minimum. Uses the SQL interval format (a positive integer followed by second, minute, hour, or day), not the short form of the materialized view granularity fields.Example: "1 minute" - promqlBackendoptionalautoorclickhouse-httportable-function
How PromQL is evaluated on a ClickHouse connection. "clickhouse-http" uses ClickHouse's Prometheus HTTP API, which needs ClickHouse 26.6+ with the prometheus_api_v1 handler configured; queries fail with an error when the server does not serve it. "table-function" uses the prometheusQuery table functions. "auto" (the default when omitted) checks the server and prefers the HTTP API. Ignored when the connection is a Prometheus-compatible endpoint.
Example: "auto"
400
The request cannot be processed due to a client error. Please verify your request parameters and try again.
500
An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance.