---
title: "List Sources"
method: GET
path: "/api/v2/sources"
tags: ["Sources"]
---

# List Sources

`GET /api/v2/sources`

Retrieves a list of all sources for the authenticated team

## Response `200`

Successfully retrieved sources

- SourcesListResponse
  - `data` Source[] — List of source objects.
    - union
      - LogSource
        - `id` string, required — Unique source ID.
        - `name` string, required — Display name for the source.
        - `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.
        - `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.
        - `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` '1s' | '15s' | '30s' | '1m' | '5m' | '15m' | '30m' | '1h' | '2h' | '6h' | '12h' | '1d' | '2d' | '7d' | '30d', required — The granularity of the timestamp column
          - `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, required — Unique source ID.
        - `name` string, required — Display name for the source.
        - `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, nullable — 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.
        - `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.
        - `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` '1s' | '15s' | '30s' | '1m' | '5m' | '15m' | '30m' | '1h' | '2h' | '6h' | '12h' | '1d' | '2d' | '7d' | '30d', required — The granularity of the timestamp column
          - `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, required — Unique source ID.
        - `name` string, required — Display name for the source.
        - `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, required — Unique source ID.
        - `name` string, required — Display name for the source.
        - `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.

## Other responses

- `401` — Unauthorized
- `403` — Forbidden

## Changes

- **2026-05-08** `6b3e524305cc` — 2 info
  - added the optional property `data/items/oneOf[#/components/schemas/LogSource]/metadataMaterializedViews` to the response with the `200` status
  - added the optional property `data/items/oneOf[#/components/schemas/TraceSource]/metadataMaterializedViews` to the response with the `200` status
- **2026-02-16** `d6176bd41435` — 30 warning, 30 info
  - added the new `12h` enum value to the `data/items/oneOf[#/components/schemas/LogSource]/materializedViews/items/minGranularity` response property for the response status `200`
  - added the new `12h` enum value to the `data/items/oneOf[#/components/schemas/TraceSource]/materializedViews/items/minGranularity` response property for the response status `200`
  - added the new `15m` enum value to the `data/items/oneOf[#/components/schemas/LogSource]/materializedViews/items/minGranularity` response property for the response status `200`
  - added the new `15m` enum value to the `data/items/oneOf[#/components/schemas/TraceSource]/materializedViews/items/minGranularity` response property for the response status `200`
  - …56 more
- **2026-02-11** `60a08cf40234` — 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/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/cec066aa8c43/schema)