> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-postgresql-tls-support.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Source

> Retrieves a specific source by ID



## OpenAPI

````yaml https://raw.githubusercontent.com/hyperdxio/hyperdx/refs/heads/main/packages/api/openapi.json get /api/v2/sources/{id}
openapi: 3.0.0
info:
  title: HyperDX External API
  description: API for managing HyperDX alerts and dashboards
  version: 2.0.0
servers:
  - url: /
    description: Your HyperDX instance (http://<host>:<port>)
security:
  - BearerAuth: []
tags:
  - name: Dashboards
    description: Endpoints for managing dashboards and their visualizations
  - name: Alerts
    description: Endpoints for managing monitoring alerts
  - name: Charts
    description: Endpoints for querying chart data
  - name: Connections
    description: Endpoints for managing ClickHouse connections
  - name: Sources
    description: Endpoints for managing data sources
  - name: Webhooks
    description: Endpoints for managing webhooks
  - name: Search
    description: Endpoints for querying raw data from log and trace sources
paths:
  /api/v2/sources/{id}:
    get:
      tags:
        - Sources
      summary: Get Source
      description: Retrieves a specific source by ID
      operationId: getSource
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Source ID
          example: 507f1f77bcf86cd799439011
      responses:
        '200':
          description: Successfully retrieved source
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceResponseEnvelope'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: Unauthorized access. API key is missing or invalid.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Source not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: Source not found
components:
  schemas:
    SourceResponseEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Source'
          description: The source object.
    Error:
      type: object
      properties:
        message:
          type: string
          description: Human-readable error message.
          example: 'NOT_FOUND: Alert not found'
    Source:
      oneOf:
        - $ref: '#/components/schemas/LogSource'
        - $ref: '#/components/schemas/TraceSource'
        - $ref: '#/components/schemas/MetricSource'
        - $ref: '#/components/schemas/SessionSource'
        - $ref: '#/components/schemas/PromqlSource'
      discriminator:
        propertyName: kind
        mapping:
          log:
            $ref: '#/components/schemas/LogSource'
          trace:
            $ref: '#/components/schemas/TraceSource'
          metric:
            $ref: '#/components/schemas/MetricSource'
          session:
            $ref: '#/components/schemas/SessionSource'
          promql:
            $ref: '#/components/schemas/PromqlSource'
    LogSource:
      type: object
      required:
        - name
        - kind
        - connection
        - from
        - defaultTableSelectExpression
        - timestampValueExpression
      properties:
        id:
          type: string
          readOnly: true
          description: >-
            Unique source ID. Server-generated; ignored if sent in create/update
            requests.
          example: 507f1f77bcf86cd799439011
        name:
          type: string
          description: Display name for the source.
          example: Logs
        section:
          type: string
          maxLength: 256
          description: >-
            Optional grouping label used to organize sources in the source
            selector. Sources that share a section value are displayed together.
          example: Billing
        disabled:
          type: boolean
          description: >-
            When true, the source is hidden from source selectors in the UI.
            Defaults to false.
          nullable: true
          example: false
        kind:
          type: string
          enum:
            - log
          description: Source kind discriminator. Must be "log" for log sources.
          example: log
        connection:
          type: string
          description: ID of the ClickHouse connection used by this source.
          example: 507f1f77bcf86cd799439012
        from:
          $ref: '#/components/schemas/SourceFrom'
          description: Database and table location of the source data.
        querySettings:
          type: array
          description: >-
            Optional ClickHouse query settings applied when querying this
            source.
          items:
            $ref: '#/components/schemas/QuerySetting'
          nullable: true
        defaultTableSelectExpression:
          type: string
          description: >-
            Default columns selected in search results (this can be customized
            per search later)
          example: Timestamp, ServiceName, SeverityText, Body
        timestampValueExpression:
          type: string
          description: >-
            DateTime column or expression that is part of your table's primary
            key.
          example: Timestamp
        serviceNameExpression:
          type: string
          description: Expression to extract the service name from log rows.
          nullable: true
          example: ServiceName
        severityTextExpression:
          type: string
          description: Expression to extract the severity/log level text.
          nullable: true
          example: SeverityText
        bodyExpression:
          type: string
          description: Expression to extract the log message body.
          nullable: true
          example: Body
        eventAttributesExpression:
          type: string
          description: Expression to extract event-level attributes.
          nullable: true
          example: LogAttributes
        resourceAttributesExpression:
          type: string
          description: Expression to extract resource-level attributes.
          nullable: true
          example: ResourceAttributes
        displayedTimestampValueExpression:
          type: string
          description: This DateTime column is used to display and order search results.
          nullable: true
          example: TimestampTime
        metricSourceId:
          type: string
          description: HyperDX Source for metrics associated with logs. Optional
          nullable: true
          example: 507f1f77bcf86cd799439013
        traceSourceId:
          type: string
          description: HyperDX Source for traces associated with logs. Optional
          nullable: true
          example: 507f1f77bcf86cd799439014
        traceIdExpression:
          type: string
          description: Expression to extract the trace ID for correlating logs with traces.
          nullable: true
          example: TraceId
        spanIdExpression:
          type: string
          description: Expression to extract the span ID for correlating logs with traces.
          nullable: true
          example: SpanId
        implicitColumnExpression:
          type: string
          description: >-
            Column used for full text search if no property is specified in a
            Lucene-based search. Typically the message body of a log.
          nullable: true
          example: Body
        knownColumnsListExpression:
          type: string
          description: >-
            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.
          nullable: true
          example: Timestamp, Body, ServiceName
        useTextIndexForImplicitColumn:
          type: string
          enum:
            - auto
            - enabled
            - disabled
          description: >-
            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.
          nullable: true
          example: auto
        highlightedTraceAttributeExpressions:
          type: array
          description: >-
            Expressions defining trace-level attributes which are displayed in
            the trace view for the selected trace.
          items:
            $ref: '#/components/schemas/HighlightedAttributeExpression'
          nullable: true
        highlightedRowAttributeExpressions:
          type: array
          description: >-
            Expressions defining row-level attributes which are displayed in the
            row side panel for the selected row.
          items:
            $ref: '#/components/schemas/HighlightedAttributeExpression'
          nullable: true
        materializedViews:
          type: array
          description: >-
            Configure materialized views for query optimization. These
            pre-aggregated views can significantly improve query performance on
            aggregation queries.
          items:
            $ref: '#/components/schemas/MaterializedView'
          nullable: true
        metadataMaterializedViews:
          type: object
          description: >-
            Configure materialized views for fast field discovery and value
            autocomplete.
          nullable: true
          properties:
            keyRollupTable:
              type: string
              description: ClickHouse table name for the key rollup (field discovery).
              example: otel_logs_key_rollup_15m
            kvRollupTable:
              type: string
              description: >-
                ClickHouse table name for the key-value rollup (value
                autocomplete).
              example: otel_logs_kv_rollup_15m
            granularity:
              type: string
              description: The time granularity of the rollup tables.
              example: 15m
    TraceSource:
      type: object
      required:
        - name
        - kind
        - connection
        - from
        - defaultTableSelectExpression
        - timestampValueExpression
        - durationExpression
        - durationPrecision
        - traceIdExpression
        - spanIdExpression
        - parentSpanIdExpression
        - spanNameExpression
        - spanKindExpression
      properties:
        id:
          type: string
          readOnly: true
          description: >-
            Unique source ID. Server-generated; ignored if sent in create/update
            requests.
          example: 507f1f77bcf86cd799439021
        name:
          type: string
          description: Display name for the source.
          example: Traces
        section:
          type: string
          maxLength: 256
          description: >-
            Optional grouping label used to organize sources in the source
            selector. Sources that share a section value are displayed together.
          example: Billing
        disabled:
          type: boolean
          description: >-
            When true, the source is hidden from source selectors in the UI.
            Defaults to false.
          nullable: true
          example: false
        kind:
          type: string
          enum:
            - trace
          description: Source kind discriminator. Must be "trace" for trace sources.
          example: trace
        connection:
          type: string
          description: ID of the ClickHouse connection used by this source.
          example: 507f1f77bcf86cd799439012
        from:
          $ref: '#/components/schemas/SourceFrom'
          description: Database and table location of the source data.
        querySettings:
          type: array
          description: >-
            Optional ClickHouse query settings applied when querying this
            source.
          items:
            $ref: '#/components/schemas/QuerySetting'
          nullable: true
        defaultTableSelectExpression:
          type: string
          description: >-
            Default columns selected in search results (this can be customized
            per search later)
          example: Timestamp, SpanName, ServiceName, Duration
        timestampValueExpression:
          type: string
          description: DateTime column or expression defines the start of the span
          example: Timestamp
        durationExpression:
          type: string
          description: Expression to extract span duration.
          example: Duration
        durationPrecision:
          type: integer
          minimum: 0
          maximum: 9
          default: 3
          description: >-
            Number of decimal digits in the duration value (e.g., 3 for
            milliseconds, 6 for microseconds, 9 for nanoseconds).
        traceIdExpression:
          type: string
          description: Expression to extract the trace ID.
          example: TraceId
        spanIdExpression:
          type: string
          description: Expression to extract the span ID.
          example: SpanId
        parentSpanIdExpression:
          type: string
          description: Expression to extract the parent span ID.
          example: ParentSpanId
        spanNameExpression:
          type: string
          description: Expression to extract the span name.
          example: SpanName
        spanKindExpression:
          type: string
          description: >-
            Expression to extract the span kind (e.g., client, server,
            internal).
          example: SpanKind
        logSourceId:
          type: string
          description: HyperDX Source for logs associated with traces. Optional
          nullable: true
          example: 507f1f77bcf86cd799439011
        sessionSourceId:
          type: string
          description: HyperDX Source for sessions associated with traces. Optional
          nullable: true
          example: 507f1f77bcf86cd799439031
        metricSourceId:
          type: string
          description: HyperDX Source for metrics associated with traces. Optional
          nullable: true
          example: 507f1f77bcf86cd799439041
        statusCodeExpression:
          type: string
          description: Expression to extract the span status code.
          nullable: true
          example: StatusCode
        statusMessageExpression:
          type: string
          description: Expression to extract the span status message.
          nullable: true
          example: StatusMessage
        serviceNameExpression:
          type: string
          description: Expression to extract the service name from trace rows.
          nullable: true
          example: ServiceName
        resourceAttributesExpression:
          type: string
          description: Expression to extract resource-level attributes.
          nullable: true
          example: ResourceAttributes
        eventAttributesExpression:
          type: string
          description: Expression to extract event-level attributes.
          nullable: true
          example: SpanAttributes
        spanEventsValueExpression:
          type: string
          description: >-
            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)
          nullable: true
          example: Events
        implicitColumnExpression:
          type: string
          description: >-
            Column used for full text search if no property is specified in a
            Lucene-based search. Typically the message body of a log.
          nullable: true
          example: SpanName
        knownColumnsListExpression:
          type: string
          description: >-
            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.
          nullable: true
          example: Timestamp, Body, ServiceName
        useTextIndexForImplicitColumn:
          type: string
          enum:
            - auto
            - enabled
            - disabled
          description: >-
            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.
          nullable: true
          example: auto
        highlightedTraceAttributeExpressions:
          type: array
          description: >-
            Expressions defining trace-level attributes which are displayed in
            the trace view for the selected trace.
          items:
            $ref: '#/components/schemas/HighlightedAttributeExpression'
          nullable: true
        highlightedRowAttributeExpressions:
          type: array
          description: >-
            Expressions defining row-level attributes which are displayed in the
            row side panel for the selected row
          items:
            $ref: '#/components/schemas/HighlightedAttributeExpression'
          nullable: true
        materializedViews:
          type: array
          description: >-
            Configure materialized views for query optimization. These
            pre-aggregated views can significantly improve query performance on
            aggregation queries.
          items:
            $ref: '#/components/schemas/MaterializedView'
          nullable: true
        metadataMaterializedViews:
          type: object
          description: >-
            Configure materialized views for fast field discovery and value
            autocomplete.
          nullable: true
          properties:
            keyRollupTable:
              type: string
              description: ClickHouse table name for the key rollup (field discovery).
              example: otel_traces_key_rollup_15m
            kvRollupTable:
              type: string
              description: >-
                ClickHouse table name for the key-value rollup (value
                autocomplete).
              example: otel_traces_kv_rollup_15m
            granularity:
              type: string
              description: The time granularity of the rollup tables.
              example: 15m
    MetricSource:
      type: object
      required:
        - name
        - kind
        - connection
        - from
        - metricTables
        - timestampValueExpression
        - resourceAttributesExpression
      properties:
        id:
          type: string
          readOnly: true
          description: >-
            Unique source ID. Server-generated; ignored if sent in create/update
            requests.
          example: 507f1f77bcf86cd799439041
        name:
          type: string
          description: Display name for the source.
          example: Metrics
        section:
          type: string
          maxLength: 256
          description: >-
            Optional grouping label used to organize sources in the source
            selector. Sources that share a section value are displayed together.
          example: Billing
        disabled:
          type: boolean
          description: >-
            When true, the source is hidden from source selectors in the UI.
            Defaults to false.
          nullable: true
          example: false
        kind:
          type: string
          enum:
            - metric
          description: Source kind discriminator. Must be "metric" for metric sources.
          example: metric
        connection:
          type: string
          description: ID of the ClickHouse connection used by this source.
          example: 507f1f77bcf86cd799439012
        from:
          $ref: '#/components/schemas/MetricSourceFrom'
          description: Database and optional table location of the metric source data.
        querySettings:
          type: array
          description: >-
            Optional ClickHouse query settings applied when querying this
            source.
          items:
            $ref: '#/components/schemas/QuerySetting'
          nullable: true
        metricTables:
          $ref: '#/components/schemas/MetricTables'
          description: Mapping of metric data types to their respective table names.
        timestampValueExpression:
          type: string
          description: >-
            DateTime column or expression that is part of your table's primary
            key.
          example: TimeUnix
        resourceAttributesExpression:
          type: string
          description: Column containing resource attributes for metrics
          example: ResourceAttributes
        logSourceId:
          type: string
          description: HyperDX Source for logs associated with metrics. Optional
          nullable: true
          example: 507f1f77bcf86cd799439011
    SessionSource:
      type: object
      required:
        - name
        - kind
        - connection
        - from
        - traceSourceId
      properties:
        id:
          type: string
          readOnly: true
          description: >-
            Unique source ID. Server-generated; ignored if sent in create/update
            requests.
          example: 507f1f77bcf86cd799439031
        name:
          type: string
          description: Display name for the source.
          example: Sessions
        section:
          type: string
          maxLength: 256
          description: >-
            Optional grouping label used to organize sources in the source
            selector. Sources that share a section value are displayed together.
          example: Billing
        disabled:
          type: boolean
          description: >-
            When true, the source is hidden from source selectors in the UI.
            Defaults to false.
          nullable: true
          example: false
        kind:
          type: string
          enum:
            - session
          description: Source kind discriminator. Must be "session" for session sources.
          example: session
        connection:
          type: string
          description: ID of the ClickHouse connection used by this source.
          example: 507f1f77bcf86cd799439012
        from:
          $ref: '#/components/schemas/SourceFrom'
          description: Database and table location of the source data.
        querySettings:
          type: array
          description: >-
            Optional ClickHouse query settings applied when querying this
            source.
          items:
            $ref: '#/components/schemas/QuerySetting'
          nullable: true
        timestampValueExpression:
          type: string
          description: >-
            DateTime column or expression that is part of your table's primary
            key.
          nullable: true
          example: TimestampTime
        traceSourceId:
          type: string
          description: HyperDX Source for traces associated with sessions.
          example: 507f1f77bcf86cd799439021
    PromqlSource:
      type: object
      description: >-
        A source backed by a Prometheus-compatible endpoint, queried with
        PromQL. The referenced connection should be a Prometheus connection
        (isPrometheusEndpoint set to true).
      required:
        - name
        - kind
        - connection
        - from
        - timestampValueExpression
      properties:
        id:
          type: string
          readOnly: true
          description: >-
            Unique source ID. Server-generated; ignored if sent in create/update
            requests.
          example: 507f1f77bcf86cd799439051
        name:
          type: string
          description: Display name for the source.
          example: Prometheus Metrics
        section:
          type: string
          maxLength: 256
          description: >-
            Optional grouping label used to organize sources in the source
            selector. Sources that share a section value are displayed together.
          example: Billing
        disabled:
          type: boolean
          description: >-
            When true, the source is hidden from source selectors in the UI.
            Defaults to false.
          nullable: true
          example: false
        kind:
          type: string
          enum:
            - promql
          description: Source kind discriminator. Must be "promql" for PromQL sources.
          example: promql
        connection:
          type: string
          description: >-
            ID of the connection used by this source. Should reference a
            Prometheus-compatible connection.
          example: 507f1f77bcf86cd799439012
        from:
          $ref: '#/components/schemas/SourceFrom'
          description: >-
            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").
        querySettings:
          type: array
          description: >-
            Optional ClickHouse query settings applied when querying this
            source.
          items:
            $ref: '#/components/schemas/QuerySetting'
          nullable: true
        timestampValueExpression:
          type: string
          description: >-
            Required by the API for all source kinds; not used when querying a
            Prometheus endpoint.
          example: timestamp
    SourceFrom:
      type: object
      required:
        - databaseName
        - tableName
      properties:
        databaseName:
          type: string
          description: ClickHouse database name
          example: otel
        tableName:
          type: string
          description: ClickHouse table name
          example: otel_logs
    QuerySetting:
      type: object
      required:
        - setting
        - value
      properties:
        setting:
          type: string
          description: ClickHouse setting name
          example: max_threads
        value:
          type: string
          description: Setting value
          example: '4'
    HighlightedAttributeExpression:
      type: object
      required:
        - sqlExpression
      properties:
        sqlExpression:
          type: string
          description: SQL expression for the attribute
          example: SpanAttributes['http.status_code']
        luceneExpression:
          type: string
          description: >-
            An optional, Lucene version of the sqlExpression expression. If
            provided, it is used when searching for this attribute value.
          nullable: true
          example: http.status_code
        alias:
          type: string
          description: Optional alias for the attribute
          nullable: true
          example: HTTP Status Code
    MaterializedView:
      type: object
      required:
        - databaseName
        - tableName
        - dimensionColumns
        - minGranularity
        - timestampColumn
        - aggregatedColumns
      properties:
        databaseName:
          type: string
          description: Database name for the materialized view
          example: otel
        tableName:
          type: string
          description: Table name for the materialized view
          example: otel_logs_mv_5m
        dimensionColumns:
          type: string
          description: >-
            Columns which are not pre-aggregated in the materialized view and
            can be used for filtering and grouping.
          example: ServiceName, SeverityText
        minGranularity:
          type: string
          description: >-
            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
        minDate:
          type: string
          format: date-time
          description: >-
            (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.
          nullable: true
          example: '2025-01-01T00:00:00Z'
        timestampColumn:
          type: string
          description: Timestamp column name
          example: Timestamp
        aggregatedColumns:
          type: array
          description: Columns which are pre-aggregated by the materialized view
          items:
            $ref: '#/components/schemas/AggregatedColumn'
    MetricSourceFrom:
      type: object
      required:
        - databaseName
      properties:
        databaseName:
          type: string
          description: ClickHouse database name
          example: otel
        tableName:
          type: string
          description: ClickHouse table name
          nullable: true
          example: otel_metrics_gauge
    MetricTables:
      type: object
      description: >-
        Mapping of metric data types to table names. At least one must be
        specified.
      properties:
        gauge:
          type: string
          description: Table containing gauge metrics data
          example: otel_metrics_gauge
        histogram:
          type: string
          description: Table containing histogram metrics data
          example: otel_metrics_histogram
        sum:
          type: string
          description: Table containing sum metrics data
          example: otel_metrics_sum
        summary:
          type: string
          description: >-
            Table containing summary metrics data. Note - not yet fully
            supported by HyperDX
          example: otel_metrics_summary
        exponential histogram:
          type: string
          description: >-
            Table containing exponential histogram metrics data. Note - not yet
            fully supported by HyperDX
          example: otel_metrics_exponential_histogram
    AggregatedColumn:
      type: object
      required:
        - mvColumn
        - aggFn
      properties:
        sourceColumn:
          type: string
          description: Source column name
          nullable: true
          example: Duration
        aggFn:
          type: string
          description: Aggregation function (e.g., count, sum, avg)
          example: sum
        mvColumn:
          type: string
          description: Materialized view column name
          example: sum__Duration
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

````