---
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[]
    - union
      - LogSource
        - `id` string, required
        - `name` string, required
        - `kind` 'log', required
        - `connection` string, required
        - `from` SourceFrom, required
          - `databaseName` string, required — ClickHouse database name
          - `tableName` string, required — ClickHouse table name
        - `querySettings` QuerySetting[], nullable
          - `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
        - `severityTextExpression` string, nullable
        - `bodyExpression` string, nullable
        - `eventAttributesExpression` string, nullable
        - `resourceAttributesExpression` string, nullable
        - `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
        - `spanIdExpression` string, nullable
        - `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
      - TraceSource
        - `id` string, required
        - `name` string, required
        - `kind` 'trace', required
        - `connection` string, required
        - `from` SourceFrom, required
          - `databaseName` string, required — ClickHouse database name
          - `tableName` string, required — ClickHouse table name
        - `querySettings` QuerySetting[], nullable
          - `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
        - `durationPrecision` integer, required
        - `traceIdExpression` string, required
        - `spanIdExpression` string, required
        - `parentSpanIdExpression` string, required
        - `spanNameExpression` string, required
        - `spanKindExpression` string, required
        - `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
        - `statusMessageExpression` string, nullable
        - `serviceNameExpression` string, nullable
        - `resourceAttributesExpression` string, nullable
        - `eventAttributesExpression` string, nullable
        - `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
      - MetricSource
        - `id` string, required
        - `name` string, required
        - `kind` 'metric', required
        - `connection` string, required
        - `from` MetricSourceFrom, required
          - `databaseName` string, required — ClickHouse database name
          - `tableName` string, nullable — ClickHouse table name
        - `querySettings` QuerySetting[], nullable
          - `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
        - `name` string, required
        - `kind` 'session', required
        - `connection` string, required
        - `from` SourceFrom, required
          - `databaseName` string, required — ClickHouse database name
          - `tableName` string, required — ClickHouse table name
        - `querySettings` QuerySetting[], nullable
          - `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-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/defc8c0a5046/schema)