List Sources

GET/api/v2/sources

Retrieves a list of all sources for the authenticated team

Authorizations

AuthorizationBearer API Keyheaderrequired
`Authorization: Bearer <token>`

Response

JSON

200

Successfully retrieved sources

JSON

dataoptionalarray ofLogSourceorTraceSourceorMetricSourceorSessionSourceorPromqlSource
List of source objects.
5 variants
One of the following:
LogSourcelog
View LogSource 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
Database and table location of the source data.

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.

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

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

2 properties
settingstringrequired
ClickHouse setting name

Example: "max_threads"
valuestringrequired
Setting value

Example: "4"
serviceNameExpressionoptionalstringor null
Expression to extract the service name from log rows.

Example: "ServiceName"
serviceVersionExpressionoptionalstringor 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']"
severityTextExpressionoptionalstringor null
Expression to extract the severity/log level text.

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

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

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

Example: "ResourceAttributes"
displayedTimestampValueExpressionoptionalstringor 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"
metricSourceIdoptionalstringor null
HyperDX Source for metrics associated with logs. Optional

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

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

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

Example: "SpanId"
implicitColumnExpressionoptionalstringor 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"
knownColumnsListExpressionoptionalstringor 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"
useTextIndexForImplicitColumnoptionalautoorenabledordisabledor null
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 ofobjector null
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']"
luceneExpressionoptionalstringor null
An optional, Lucene version of the sqlExpression expression. If provided, it is used when searching for this attribute value.

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

Example: "HTTP Status Code"
highlightedRowAttributeExpressionsoptionalarray ofobjector null
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']"
luceneExpressionoptionalstringor null
An optional, Lucene version of the sqlExpression expression. If provided, it is used when searching for this attribute value.

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

Example: "HTTP Status Code"
materializedViewsoptionalarray ofobjector null
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.

pattern: ^\d+(s|m|h|d)$
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"
sourceColumnoptionalstringor null
Source column name

Example: "Duration"
minDateoptionalstringor 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"
metadataMaterializedViewsoptionalobjector null
Configure materialized views for fast field discovery and value autocomplete.

3 properties
keyRollupTableoptionalstring
ClickHouse table name for the key rollup (field discovery).

Example: "otel_logs_key_rollup_15m"
kvRollupTableoptionalstring
ClickHouse table name for the key-value rollup (value autocomplete).

Example: "otel_logs_kv_rollup_15m"
granularityoptionalstring
The time granularity of the rollup tables.

Example: "15m"
TraceSourcetrace
View TraceSource schema →
38 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
Database and table location of the source data.

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).

maximum: 9, minimum: 0
Default: 3
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.

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

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

2 properties
settingstringrequired
ClickHouse setting name

Example: "max_threads"
valuestringrequired
Setting value

Example: "4"
logSourceIdoptionalstringor null
HyperDX Source for logs associated with traces. Optional

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

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

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

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

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

Example: "ServiceName"
serviceVersionExpressionoptionalstringor 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"
resourceAttributesExpressionoptionalstringor null
Expression to extract resource-level attributes.

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

Example: "SpanAttributes"
spanEventsValueExpressionoptionalstringor 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"
implicitColumnExpressionoptionalstringor 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"
knownColumnsListExpressionoptionalstringor 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"
useTextIndexForImplicitColumnoptionalautoorenabledordisabledor null
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 ofobjector null
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']"
luceneExpressionoptionalstringor null
An optional, Lucene version of the sqlExpression expression. If provided, it is used when searching for this attribute value.

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

Example: "HTTP Status Code"
highlightedRowAttributeExpressionsoptionalarray ofobjector null
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']"
luceneExpressionoptionalstringor null
An optional, Lucene version of the sqlExpression expression. If provided, it is used when searching for this attribute value.

Example: "http.status_code"
aliasoptionalstringor 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 ofobjector null
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.

pattern: ^\d+(s|m|h|d)$
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"
sourceColumnoptionalstringor null
Source column name

Example: "Duration"
minDateoptionalstringor 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"
metadataMaterializedViewsoptionalobjector null
Configure materialized views for fast field discovery and value autocomplete.

3 properties
keyRollupTableoptionalstring
ClickHouse table name for the key rollup (field discovery).

Example: "otel_traces_key_rollup_15m"
kvRollupTableoptionalstring
ClickHouse table name for the key-value rollup (value autocomplete).

Example: "otel_traces_kv_rollup_15m"
granularityoptionalstring
The time granularity of the rollup tables.

Example: "15m"
MetricSourcemetric
View MetricSource 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
Database and optional table location of the metric source data.

2 properties
databaseNamestringrequired
ClickHouse database name

Example: "otel"
tableNameoptionalstringor null
ClickHouse table name

Example: "otel_metrics_gauge"
metricTablesobjectrequired
Mapping of metric data types to their respective table names.

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.

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

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

2 properties
settingstringrequired
ClickHouse setting name

Example: "max_threads"
valuestringrequired
Setting value

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

Example: "507f1f77bcf86cd799439011"
SessionSourcesession
View SessionSource schema →
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"
fromobjectrequired
Database and table location of the source data.

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.

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

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

2 properties
settingstringrequired
ClickHouse setting name

Example: "max_threads"
valuestringrequired
Setting value

Example: "4"
timestampValueExpressionoptionalstringor 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"
PromqlSourcepromql
View PromqlSource 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
Required by the API for all source kinds; not used when querying a Prometheus endpoint (empty strings are not accepted — use placeholder values such as "default").

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.

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

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

2 properties
settingstringrequired
ClickHouse setting name

Example: "max_threads"
valuestringrequired
Setting value

Example: "4"

List Sources

curl --request GET \
  --url /api/v2/sources \
  --header 'Authorization: Bearer <token>'

const url = '/api/v2/sources';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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

Response example

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "Logs",
      "section": "Billing",
      "disabled": false,
      "kind": "log",
      "connection": "507f1f77bcf86cd799439012",
      "from": {
        "databaseName": "otel",
        "tableName": "otel_logs"
      },
      "querySettings": [
        {
          "setting": "max_threads",
          "value": "4"
        }
      ],
      "defaultTableSelectExpression": "Timestamp, ServiceName, SeverityText, Body",
      "timestampValueExpression": "Timestamp",
      "serviceNameExpression": "ServiceName",
      "serviceVersionExpression": "ResourceAttributes['service.version']",
      "severityTextExpression": "SeverityText",
      "bodyExpression": "Body",
      "eventAttributesExpression": "LogAttributes",
      "resourceAttributesExpression": "ResourceAttributes",
      "displayedTimestampValueExpression": "TimestampTime",
      "orderByExpression": "Timestamp DESC",
      "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"
      }
    }
  ]
}

{
  "message": "Unauthorized access. API key is missing or invalid."
}

{
  "message": "NOT_FOUND: Alert not found"
}

Authorizations

Response

200

401

403