openapi: 3.0.0
info:
  title: Lightdash AiAgents Explorer API
  version: 0.3156.1
  description: 'Open API documentation for all public Lightdash API endpoints. # Authentication Before you get started, you might need to create a Personal Access Token to authenticate via the API. You can create a token by following this guide: https://docs.lightdash.com/references/personal_tokens

    '
  license:
    name: MIT
  contact:
    name: Lightdash Support
    email: support@lightdash.com
    url: https://docs.lightdash.com/help-and-contact/contact/contact_info/
servers:
- url: /
tags:
- name: Explorer
paths:
  /api/v1/projects/{projectUuid}/metricsExplorer/{explore}/{metric}/runMetricTotal:
    post:
      operationId: runMetricTotal
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiMetricsExplorerTotalResults'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Run a metric total query with comparison
      summary: Run metric total query
      tags:
      - Explorer
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - in: path
        name: explore
        required: true
        schema:
          type: string
      - in: path
        name: metric
        required: true
        schema:
          type: string
      - in: query
        name: timeFrame
        required: true
        schema:
          $ref: '#/components/schemas/TimeFrames'
      - in: query
        name: granularity
        required: true
        schema:
          $ref: '#/components/schemas/TimeFrames'
      - in: query
        name: startDate
        required: true
        schema:
          type: string
      - in: query
        name: endDate
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              properties:
                rollingDays:
                  type: number
                  format: double
                comparisonType:
                  $ref: '#/components/schemas/MetricTotalComparisonType'
              type: object
  /api/v1/projects/{projectUuid}/metricsExplorer/{explore}/{metric}/compileMetricTotalQuery:
    post:
      operationId: compileMetricTotalQuery
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                properties:
                  results:
                    $ref: '#/components/schemas/ApiCompiledQueryResults'
                  status:
                    type: string
                    enum:
                    - ok
                    nullable: false
                required:
                - results
                - status
                type: object
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Compile the metric total query SQL
      summary: Compile metric total query
      tags:
      - Explorer
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - in: path
        name: explore
        required: true
        schema:
          type: string
      - in: path
        name: metric
        required: true
        schema:
          type: string
      - in: query
        name: timeFrame
        required: true
        schema:
          $ref: '#/components/schemas/TimeFrames'
      - in: query
        name: granularity
        required: true
        schema:
          $ref: '#/components/schemas/TimeFrames'
      - in: query
        name: startDate
        required: true
        schema:
          type: string
      - in: query
        name: endDate
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              properties:
                rollingDays:
                  type: number
                  format: double
                comparisonType:
                  $ref: '#/components/schemas/MetricTotalComparisonType'
              type: object
components:
  schemas:
    MetricWithAssociatedTimeDimension:
      allOf:
      - $ref: '#/components/schemas/CompiledMetric'
      - properties:
          availableTimeDimensions:
            items:
              allOf:
              - $ref: '#/components/schemas/CompiledDimension'
              - properties:
                  type:
                    anyOf:
                    - $ref: '#/components/schemas/DimensionType.DATE'
                    - $ref: '#/components/schemas/DimensionType.TIMESTAMP'
                required:
                - type
                type: object
            type: array
          timeDimension:
            allOf:
            - $ref: '#/components/schemas/DefaultTimeDimension'
            - properties:
                table:
                  type: string
              required:
              - table
              type: object
        type: object
    CustomFormat:
      properties:
        type:
          $ref: '#/components/schemas/CustomFormatType'
          description: Format type
        round:
          type: number
          format: double
          description: Number of decimal places
        separator:
          $ref: '#/components/schemas/NumberSeparator'
          description: Number separator style
        currency:
          type: string
          description: Currency code (e.g., USD, GBP, EUR)
        compact:
          $ref: '#/components/schemas/CompactOrAlias'
          description: Compact format for large numbers (K, M, B, T) or byte units
        prefix:
          type: string
          description: Prefix to prepend to formatted values
        suffix:
          type: string
          description: Suffix to append to formatted values
        timeInterval:
          $ref: '#/components/schemas/TimeFrames'
          description: Time interval for date formatting
        custom:
          type: string
          description: Custom format string
      required:
      - type
      type: object
      additionalProperties: true
    MetricType:
      enum:
      - percentile
      - average
      - count
      - count_distinct
      - sum
      - sum_distinct
      - average_distinct
      - min
      - max
      - percent_of_previous
      - percent_of_total
      - running_total
      - number
      - median
      - string
      - date
      - timestamp
      - boolean
      type: string
    FieldType.DIMENSION:
      enum:
      - dimension
      type: string
    FieldCompilationError:
      properties:
        message:
          type: string
      required:
      - message
      type: object
      description: 'Error information stored on a field when compilation fails but

        partial compilation mode is enabled.'
    NumberSeparator:
      enum:
      - default
      - commaPeriod
      - spacePeriod
      - periodComma
      - noSeparatorPeriod
      - apostrophePeriod
      type: string
    FieldUrl:
      properties:
        label:
          type: string
        url:
          type: string
      required:
      - label
      - url
      type: object
    MetricTotalResults:
      properties:
        metric:
          $ref: '#/components/schemas/MetricWithAssociatedTimeDimension'
        comparisonValue:
          type: number
          format: double
          nullable: true
        value:
          type: number
          format: double
          nullable: true
      required:
      - metric
      - comparisonValue
      - value
      type: object
    Dimension:
      properties:
        fieldType:
          $ref: '#/components/schemas/FieldType.DIMENSION'
        type:
          $ref: '#/components/schemas/DimensionType'
        name:
          type: string
        label:
          type: string
        table:
          type: string
        tableLabel:
          type: string
        sql:
          type: string
        description:
          type: string
        source:
          $ref: '#/components/schemas/Source'
        hidden:
          type: boolean
        compact:
          $ref: '#/components/schemas/CompactOrAlias'
        round:
          type: number
          format: double
        format:
          anyOf:
          - $ref: '#/components/schemas/Format'
          - type: string
        separator:
          $ref: '#/components/schemas/NumberSeparator'
          description: 'Number separator style for grouping/decimal characters. Composes with

            `format` (including ECMA-376 expressions) and `formatOptions` — it only

            controls the separator characters, not the format shape.'
        groupLabel:
          type: string
          deprecated: true
        groups:
          items:
            type: string
          type: array
        urls:
          items:
            $ref: '#/components/schemas/FieldUrl'
          type: array
        index:
          type: number
          format: double
        tags:
          items:
            type: string
          type: array
        parameterReferences:
          items:
            type: string
          type: array
        group:
          type: string
          deprecated: true
        requiredAttributes:
          $ref: '#/components/schemas/Record_string.string-or-string-Array_'
        anyAttributes:
          $ref: '#/components/schemas/Record_string.string-or-string-Array_'
        timeInterval:
          $ref: '#/components/schemas/TimeFrames'
        timeIntervalBaseDimensionName:
          type: string
        timeIntervalBaseDimensionType:
          $ref: '#/components/schemas/DimensionType'
        customTimeInterval:
          type: string
        isAdditionalDimension:
          type: boolean
        skipTimezoneConversion:
          type: boolean
        colors:
          $ref: '#/components/schemas/Record_string.string_'
        isIntervalBase:
          type: boolean
        aiHint:
          anyOf:
          - type: string
          - items:
              type: string
            type: array
        formatOptions:
          $ref: '#/components/schemas/CustomFormat'
        caseSensitive:
          type: boolean
        image:
          properties:
            fit:
              type: string
            height:
              type: number
              format: double
            width:
              type: number
              format: double
            url:
              type: string
          required:
          - url
          type: object
        richText:
          type: string
        spotlight:
          properties:
            segmentBy:
              type: boolean
            filterBy:
              type: boolean
          type: object
      required:
      - fieldType
      - type
      - name
      - label
      - table
      - tableLabel
      - sql
      - hidden
      type: object
      additionalProperties: true
    MetricTotalComparisonType:
      enum:
      - none
      - previous_period
      - rolling_days
      type: string
    DimensionType.TIMESTAMP:
      enum:
      - timestamp
      type: string
    DefaultTimeDimension:
      properties:
        interval:
          $ref: '#/components/schemas/TimeFrames'
        field:
          type: string
      required:
      - interval
      - field
      type: object
    Metric:
      properties:
        fieldType:
          $ref: '#/components/schemas/FieldType.METRIC'
        type:
          $ref: '#/components/schemas/MetricType'
        name:
          type: string
        label:
          type: string
        table:
          type: string
        tableLabel:
          type: string
        sql:
          type: string
        description:
          type: string
        source:
          $ref: '#/components/schemas/Source'
        hidden:
          type: boolean
        compact:
          $ref: '#/components/schemas/CompactOrAlias'
        round:
          type: number
          format: double
        format:
          anyOf:
          - $ref: '#/components/schemas/Format'
          - type: string
        separator:
          $ref: '#/components/schemas/NumberSeparator'
          description: 'Number separator style for grouping/decimal characters. Composes with

            `format` (including ECMA-376 expressions) and `formatOptions` — it only

            controls the separator characters, not the format shape.'
        groupLabel:
          type: string
          deprecated: true
        groups:
          items:
            type: string
          type: array
        urls:
          items:
            $ref: '#/components/schemas/FieldUrl'
          type: array
        index:
          type: number
          format: double
        tags:
          items:
            type: string
          type: array
        parameterReferences:
          items:
            type: string
          type: array
        showUnderlyingValues:
          items:
            type: string
          type: array
        filters:
          items:
            $ref: '#/components/schemas/MetricFilterRule'
          type: array
        percentile:
          type: number
          format: double
        distinctKeys:
          items:
            type: string
          type: array
        formatOptions:
          $ref: '#/components/schemas/CustomFormat'
        dimensionReference:
          type: string
        requiredAttributes:
          $ref: '#/components/schemas/Record_string.string-or-string-Array_'
        anyAttributes:
          $ref: '#/components/schemas/Record_string.string-or-string-Array_'
        defaultTimeDimension:
          $ref: '#/components/schemas/DefaultTimeDimension'
        spotlight:
          properties:
            owner:
              type: string
            defaultFilter:
              $ref: '#/components/schemas/MetricFilterRule'
            defaultSegment:
              type: string
            segmentBy:
              items:
                type: string
              type: array
            filterBy:
              items:
                type: string
              type: array
            categories:
              items:
                type: string
              type: array
            visibility:
              type: string
              enum:
              - show
              - hide
          required:
          - visibility
          type: object
        drivers:
          items:
            type: string
          type: array
        aiHint:
          anyOf:
          - type: string
          - items:
              type: string
            type: array
        richText:
          type: string
      required:
      - fieldType
      - type
      - name
      - label
      - table
      - tableLabel
      - sql
      - hidden
      type: object
      additionalProperties: true
    FieldType.METRIC:
      enum:
      - metric
      type: string
    AnyType:
      description: 'This AnyType is an alias for any

        The goal is to make it easier to identify any type in the codebase

        without having to eslint-disable all the time

        These are only used on legacy `any` types, don''t use it for new types.

        This is added on a separate file to avoid circular dependencies.'
    SourcePosition:
      properties:
        character:
          type: number
          format: double
        line:
          type: number
          format: double
      required:
      - character
      - line
      type: object
    ApiMetricsExplorerTotalResults:
      properties:
        results:
          $ref: '#/components/schemas/MetricTotalResults'
        status:
          type: string
          enum:
          - ok
          nullable: false
      required:
      - results
      - status
      type: object
    ApiErrorPayload:
      properties:
        error:
          properties:
            data:
              $ref: '#/components/schemas/AnyType'
              description: Optional data containing details of the error
            message:
              type: string
              description: A friendly message summarising the error
            name:
              type: string
              description: Unique name for the type of error
            statusCode:
              type: number
              format: integer
              description: HTTP status code
          required:
          - name
          - statusCode
          type: object
        status:
          type: string
          enum:
          - error
          nullable: false
      required:
      - error
      - status
      type: object
      description: 'The Error object is returned from the api any time there is an error.

        The message contains'
    TimeFrames:
      enum:
      - RAW
      - YEAR
      - QUARTER
      - MONTH
      - WEEK
      - DAY
      - HOUR
      - MINUTE
      - SECOND
      - MILLISECOND
      - DAY_OF_WEEK_INDEX
      - DAY_OF_MONTH_NUM
      - DAY_OF_YEAR_NUM
      - WEEK_NUM
      - MONTH_NUM
      - QUARTER_NUM
      - YEAR_NUM
      - DAY_OF_WEEK_NAME
      - MONTH_NAME
      - QUARTER_NAME
      - HOUR_OF_DAY_NUM
      - MINUTE_OF_HOUR_NUM
      type: string
    Record_string.Record_string.string-or-string-Array__:
      properties: {}
      additionalProperties:
        $ref: '#/components/schemas/Record_string.string-or-string-Array_'
      type: object
      description: Construct a type with a set of properties K of type T
    FilterOperator:
      enum:
      - isNull
      - notNull
      - equals
      - notEquals
      - startsWith
      - endsWith
      - include
      - doesNotInclude
      - lessThan
      - lessThanOrEqual
      - greaterThan
      - greaterThanOrEqual
      - inThePast
      - notInThePast
      - inTheNext
      - inTheCurrent
      - notInTheCurrent
      - inBetween
      - notInBetween
      - inPeriodToDate
      type: string
    CompiledProperties:
      properties:
        compiledDistinctKeys:
          items:
            type: string
          type: array
        compiledValueSql:
          type: string
        compilationError:
          $ref: '#/components/schemas/FieldCompilationError'
          description: 'When partial compilation mode is enabled, fields that fail to compile

            will have this property set instead of causing the entire explore to fail.'
        tablesAnyAttributes:
          $ref: '#/components/schemas/Record_string.Record_string.string-or-string-Array__'
        tablesRequiredAttributes:
          $ref: '#/components/schemas/Record_string.Record_string.string-or-string-Array__'
        tablesReferences:
          items:
            type: string
          type: array
        compiledSql:
          type: string
      required:
      - compiledSql
      type: object
    Record_string.string-or-string-Array_:
      properties: {}
      additionalProperties:
        anyOf:
        - type: string
        - items:
            type: string
          type: array
      type: object
      description: Construct a type with a set of properties K of type T
    CustomFormatType:
      enum:
      - default
      - percent
      - currency
      - number
      - id
      - date
      - timestamp
      - bytes_si
      - bytes_iec
      - custom
      type: string
    ApiCompiledQueryResults:
      properties:
        compilationErrors:
          items:
            type: string
          type: array
        parameterReferences:
          items:
            type: string
          type: array
        pivotQuery:
          type: string
        query:
          type: string
      required:
      - parameterReferences
      - query
      type: object
    CompactOrAlias:
      anyOf:
      - $ref: '#/components/schemas/Compact'
      - type: string
        enum:
        - K
        - thousand
        - M
        - million
        - B
        - billion
        - T
        - trillion
        - KB
        - kilobyte
        - MB
        - megabyte
        - GB
        - gigabyte
        - TB
        - terabyte
        - PB
        - petabyte
        - KiB
        - kibibyte
        - MiB
        - mebibyte
        - GiB
        - gibibyte
        - TiB
        - tebibyte
        - PiB
        - pebibyte
    DimensionType.DATE:
      enum:
      - date
      type: string
    Record_string.string_:
      properties: {}
      additionalProperties:
        type: string
      type: object
      description: Construct a type with a set of properties K of type T
    Compact:
      enum:
      - thousands
      - millions
      - billions
      - trillions
      - kilobytes
      - megabytes
      - gigabytes
      - terabytes
      - petabytes
      - kibibytes
      - mebibytes
      - gibibytes
      - tebibytes
      - pebibytes
      type: string
    Source:
      properties:
        content:
          type: string
        highlight:
          properties:
            end:
              $ref: '#/components/schemas/SourcePosition'
            start:
              $ref: '#/components/schemas/SourcePosition'
          required:
          - end
          - start
          type: object
        range:
          properties:
            end:
              $ref: '#/components/schemas/SourcePosition'
            start:
              $ref: '#/components/schemas/SourcePosition'
          required:
          - end
          - start
          type: object
        path:
          type: string
      required:
      - content
      - range
      - path
      type: object
    DimensionType:
      enum:
      - string
      - number
      - timestamp
      - date
      - boolean
      type: string
    CompiledDimension:
      allOf:
      - $ref: '#/components/schemas/Dimension'
      - $ref: '#/components/schemas/CompiledProperties'
    Format:
      enum:
      - km
      - mi
      - usd
      - gbp
      - eur
      - jpy
      - dkk
      - id
      - percent
      type: string
    CompiledMetric:
      allOf:
      - $ref: '#/components/schemas/Metric'
      - $ref: '#/components/schemas/CompiledProperties'
    MetricFilterRule:
      description: Filter rule for metrics, targeting fields by reference
      properties:
        values:
          items:
            $ref: '#/components/schemas/AnyType'
          type: array
          description: Values to filter by
        operator:
          $ref: '#/components/schemas/FilterOperator'
          description: Filter operator
        id:
          type: string
          description: Unique identifier for the filter
        target:
          properties:
            fieldRef:
              type: string
              description: Field reference to filter on (e.g., 'table_name.field_name')
          required:
          - fieldRef
          type: object
          description: Target field for the filter
        settings:
          $ref: '#/components/schemas/AnyType'
          description: Additional settings for date/time filters
        disabled:
          type: boolean
          description: Whether this filter is disabled
        required:
          type: boolean
          description: Whether this filter is required
        caseSensitive:
          type: boolean
          description: 'Overrides the field/explore case-sensitivity for this rule only.

            Used by internal features like autocomplete search that must always

            match case-insensitively regardless of the field''s configured setting.'
      required:
      - operator
      - id
      - target
      type: object
      additionalProperties: true
  securitySchemes:
    session_cookie:
      type: apiKey
      in: cookie
      name: connect.sid
    api_key:
      type: apiKey
      in: header
      name: Authorization
      description: Value should be 'ApiKey <your key>'