--- title: "Get Source" method: GET path: "/api/v2/sources/{id}" tags: ["Sources"] --- # Get Source `GET /api/v2/sources/{id}` Retrieves a specific source by ID ## Path parameters - `id` string, required ## Response `200` Successfully retrieved source - SourceResponseEnvelope - `data` union - LogSource - `id` string — Unique source ID. Server-generated; ignored if sent in create/update requests. - `name` string, required — Display name for the source. - `section` string — Optional grouping label used to organize sources in the source selector. Sources that share a section value are displayed together. - `disabled` boolean, nullable — When true, the source is hidden from source selectors in the UI. Defaults to false. - `kind` 'log', required — Source kind discriminator. Must be "log" for log sources. - `connection` string, required — ID of the ClickHouse connection used by this source. - `from` SourceFrom, required - `databaseName` string, required — ClickHouse database name - `tableName` string, required — ClickHouse table name - `querySettings` QuerySetting[], nullable — Optional ClickHouse query settings applied when querying this source. - `setting` string, required — ClickHouse setting name - `value` string, required — Setting value - `defaultTableSelectExpression` string, required — Default columns selected in search results (this can be customized per search later) - `timestampValueExpression` string, required — DateTime column or expression that is part of your table's primary key. - `serviceNameExpression` string, nullable — Expression to extract the service name from log rows. - `serviceVersionExpression` string, nullable — 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, '')). - `severityTextExpression` string, nullable — Expression to extract the severity/log level text. - `bodyExpression` string, nullable — Expression to extract the log message body. - `eventAttributesExpression` string, nullable — Expression to extract event-level attributes. - `resourceAttributesExpression` string, nullable — Expression to extract resource-level attributes. - `displayedTimestampValueExpression` string, nullable — This DateTime column is used to display and order search results. - `metricSourceId` string, nullable — HyperDX Source for metrics associated with logs. Optional - `traceSourceId` string, nullable — HyperDX Source for traces associated with logs. Optional - `traceIdExpression` string, nullable — Expression to extract the trace ID for correlating logs with traces. - `spanIdExpression` string, nullable — Expression to extract the span ID for correlating logs with traces. - `implicitColumnExpression` string, nullable — Column used for full text search if no property is specified in a Lucene-based search. Typically the message body of a log. - `knownColumnsListExpression` string, nullable — 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. - `useTextIndexForImplicitColumn` 'auto' | 'enabled' | 'disabled', nullable — 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. - `highlightedTraceAttributeExpressions` HighlightedAttributeExpression[], nullable — Expressions defining trace-level attributes which are displayed in the trace view for the selected trace. - `sqlExpression` string, required — SQL expression for the attribute - `luceneExpression` string, nullable — An optional, Lucene version of the sqlExpression expression. If provided, it is used when searching for this attribute value. - `alias` string, nullable — Optional alias for the attribute - `highlightedRowAttributeExpressions` HighlightedAttributeExpression[], nullable — Expressions defining row-level attributes which are displayed in the row side panel for the selected row. - `sqlExpression` string, required — SQL expression for the attribute - `luceneExpression` string, nullable — An optional, Lucene version of the sqlExpression expression. If provided, it is used when searching for this attribute value. - `alias` string, nullable — Optional alias for the attribute - `materializedViews` MaterializedView[], nullable — Configure materialized views for query optimization. These pre-aggregated views can significantly improve query performance on aggregation queries. - `databaseName` string, required — Database name for the materialized view - `tableName` string, required — Table name for the materialized view - `dimensionColumns` string, required — Columns which are not pre-aggregated in the materialized view and can be used for filtering and grouping. - `minGranularity` string, required — 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. - `minDate` string, date-time, nullable — (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. - `timestampColumn` string, required — Timestamp column name - `aggregatedColumns` AggregatedColumn[], required — Columns which are pre-aggregated by the materialized view - `sourceColumn` string, nullable — Source column name - `aggFn` string, required — Aggregation function (e.g., count, sum, avg) - `mvColumn` string, required — Materialized view column name - `metadataMaterializedViews` object, nullable — Configure materialized views for fast field discovery and value autocomplete. - `keyRollupTable` string — ClickHouse table name for the key rollup (field discovery). - `kvRollupTable` string — ClickHouse table name for the key-value rollup (value autocomplete). - `granularity` string — The time granularity of the rollup tables. - TraceSource - `id` string — Unique source ID. Server-generated; ignored if sent in create/update requests. - `name` string, required — Display name for the source. - `section` string — Optional grouping label used to organize sources in the source selector. Sources that share a section value are displayed together. - `disabled` boolean, nullable — When true, the source is hidden from source selectors in the UI. Defaults to false. - `kind` 'trace', required — Source kind discriminator. Must be "trace" for trace sources. - `connection` string, required — ID of the ClickHouse connection used by this source. - `from` SourceFrom, required - `databaseName` string, required — ClickHouse database name - `tableName` string, required — ClickHouse table name - `querySettings` QuerySetting[], nullable — Optional ClickHouse query settings applied when querying this source. - `setting` string, required — ClickHouse setting name - `value` string, required — Setting value - `defaultTableSelectExpression` string, required — Default columns selected in search results (this can be customized per search later) - `timestampValueExpression` string, required — DateTime column or expression defines the start of the span - `durationExpression` string, required — Expression to extract span duration. - `durationPrecision` integer, required — Number of decimal digits in the duration value (e.g., 3 for milliseconds, 6 for microseconds, 9 for nanoseconds). - `traceIdExpression` string, required — Expression to extract the trace ID. - `spanIdExpression` string, required — Expression to extract the span ID. - `parentSpanIdExpression` string, required — Expression to extract the parent span ID. - `spanNameExpression` string, required — Expression to extract the span name. - `spanKindExpression` string, required — Expression to extract the span kind (e.g., client, server, internal). - `logSourceId` string, nullable — HyperDX Source for logs associated with traces. Optional - `sessionSourceId` string, nullable — HyperDX Source for sessions associated with traces. Optional - `metricSourceId` string, nullable — HyperDX Source for metrics associated with traces. Optional - `statusCodeExpression` string, nullable — Expression to extract the span status code. - `statusMessageExpression` string, nullable — Expression to extract the span status message. - `serviceNameExpression` string, nullable — Expression to extract the service name from trace rows. - `serviceVersionExpression` string, nullable — 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, '')). - `resourceAttributesExpression` string, nullable — Expression to extract resource-level attributes. - `eventAttributesExpression` string, nullable — Expression to extract event-level attributes. - `spanEventsValueExpression` string, nullable — 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) - `implicitColumnExpression` string, nullable — Column used for full text search if no property is specified in a Lucene-based search. Typically the message body of a log. - `knownColumnsListExpression` string, nullable — 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. - `useTextIndexForImplicitColumn` 'auto' | 'enabled' | 'disabled', nullable — 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. - `highlightedTraceAttributeExpressions` HighlightedAttributeExpression[], nullable — Expressions defining trace-level attributes which are displayed in the trace view for the selected trace. - `sqlExpression` string, required — SQL expression for the attribute - `luceneExpression` string, nullable — An optional, Lucene version of the sqlExpression expression. If provided, it is used when searching for this attribute value. - `alias` string, nullable — Optional alias for the attribute - `highlightedRowAttributeExpressions` HighlightedAttributeExpression[], nullable — Expressions defining row-level attributes which are displayed in the row side panel for the selected row - `sqlExpression` string, required — SQL expression for the attribute - `luceneExpression` string, nullable — An optional, Lucene version of the sqlExpression expression. If provided, it is used when searching for this attribute value. - `alias` string, nullable — Optional alias for the attribute - `materializedViews` MaterializedView[], nullable — Configure materialized views for query optimization. These pre-aggregated views can significantly improve query performance on aggregation queries. - `databaseName` string, required — Database name for the materialized view - `tableName` string, required — Table name for the materialized view - `dimensionColumns` string, required — Columns which are not pre-aggregated in the materialized view and can be used for filtering and grouping. - `minGranularity` string, required — 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. - `minDate` string, date-time, nullable — (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. - `timestampColumn` string, required — Timestamp column name - `aggregatedColumns` AggregatedColumn[], required — Columns which are pre-aggregated by the materialized view - `sourceColumn` string, nullable — Source column name - `aggFn` string, required — Aggregation function (e.g., count, sum, avg) - `mvColumn` string, required — Materialized view column name - `metadataMaterializedViews` object, nullable — Configure materialized views for fast field discovery and value autocomplete. - `keyRollupTable` string — ClickHouse table name for the key rollup (field discovery). - `kvRollupTable` string — ClickHouse table name for the key-value rollup (value autocomplete). - `granularity` string — The time granularity of the rollup tables. - MetricSource - `id` string — Unique source ID. Server-generated; ignored if sent in create/update requests. - `name` string, required — Display name for the source. - `section` string — Optional grouping label used to organize sources in the source selector. Sources that share a section value are displayed together. - `disabled` boolean, nullable — When true, the source is hidden from source selectors in the UI. Defaults to false. - `kind` 'metric', required — Source kind discriminator. Must be "metric" for metric sources. - `connection` string, required — ID of the ClickHouse connection used by this source. - `from` MetricSourceFrom, required - `databaseName` string, required — ClickHouse database name - `tableName` string, nullable — ClickHouse table name - `querySettings` QuerySetting[], nullable — Optional ClickHouse query settings applied when querying this source. - `setting` string, required — ClickHouse setting name - `value` string, required — Setting value - `metricTables` MetricTables, required — Mapping of metric data types to table names. At least one must be specified. - `gauge` string — Table containing gauge metrics data - `histogram` string — Table containing histogram metrics data - `sum` string — Table containing sum metrics data - `summary` string — Table containing summary metrics data. Note - not yet fully supported by HyperDX - `exponential histogram` string — Table containing exponential histogram metrics data. Note - not yet fully supported by HyperDX - `timestampValueExpression` string, required — DateTime column or expression that is part of your table's primary key. - `resourceAttributesExpression` string, required — Column containing resource attributes for metrics - `logSourceId` string, nullable — HyperDX Source for logs associated with metrics. Optional - SessionSource - `id` string — Unique source ID. Server-generated; ignored if sent in create/update requests. - `name` string, required — Display name for the source. - `section` string — Optional grouping label used to organize sources in the source selector. Sources that share a section value are displayed together. - `disabled` boolean, nullable — When true, the source is hidden from source selectors in the UI. Defaults to false. - `kind` 'session', required — Source kind discriminator. Must be "session" for session sources. - `connection` string, required — ID of the ClickHouse connection used by this source. - `from` SourceFrom, required - `databaseName` string, required — ClickHouse database name - `tableName` string, required — ClickHouse table name - `querySettings` QuerySetting[], nullable — Optional ClickHouse query settings applied when querying this source. - `setting` string, required — ClickHouse setting name - `value` string, required — Setting value - `timestampValueExpression` string, nullable — DateTime column or expression that is part of your table's primary key. - `traceSourceId` string, required — HyperDX Source for traces associated with sessions. - PromqlSource — A source backed by a Prometheus-compatible endpoint, queried with PromQL. The referenced connection should be a Prometheus connection (isPrometheusEndpoint set to true). - `id` string — Unique source ID. Server-generated; ignored if sent in create/update requests. - `name` string, required — Display name for the source. - `section` string — Optional grouping label used to organize sources in the source selector. Sources that share a section value are displayed together. - `disabled` boolean, nullable — When true, the source is hidden from source selectors in the UI. Defaults to false. - `kind` 'promql', required — Source kind discriminator. Must be "promql" for PromQL sources. - `connection` string, required — ID of the connection used by this source. Should reference a Prometheus-compatible connection. - `from` SourceFrom, required - `databaseName` string, required — ClickHouse database name - `tableName` string, required — ClickHouse table name - `querySettings` QuerySetting[], nullable — Optional ClickHouse query settings applied when querying this source. - `setting` string, required — ClickHouse setting name - `value` string, required — Setting value - `timestampValueExpression` string, required — Required by the API for all source kinds; not used when querying a Prometheus endpoint. ## Other responses - `401` — Unauthorized - `403` — Forbidden - `404` — Source not found ## Changes - **2026-08-12** `f7a811ed1346` — 2 info - added the optional property `data/oneOf[#/components/schemas/LogSource]/serviceVersionExpression` to the response with the `200` status - added the optional property `data/oneOf[#/components/schemas/TraceSource]/serviceVersionExpression` to the response with the `200` status - **2026-07-03** `10d5f1caa3d4` — 1 info - endpoint added - **2026-01-30** `ed852374c451` — 1 breaking - api path removed without deprecation [Change history](https://skmtc.dev/hyperdxio/apis/hyperdx-external-api/changes/api/v2/sources/:id/get.md) --- [API](https://skmtc.dev/hyperdxio/apis/hyperdx-external-api.md) · [All operations](https://skmtc.dev/hyperdxio/apis/hyperdx-external-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/hyperdxio/hyperdx-external-api/revisions/3399efdca551/schema)