---
title: "Get metrics with time dimensions"
method: GET
path: "/api/v1/projects/{projectUuid}/dataCatalog/metrics-with-time-dimensions"
tags: ["Catalog"]
---

# Get metrics with time dimensions

`GET /api/v1/projects/{projectUuid}/dataCatalog/metrics-with-time-dimensions`

Get metrics with time dimensions

## Path parameters

- `projectUuid` string, required

## Query parameters

- `tableName` string

## Response `200`

Success

- ApiMetricsWithAssociatedTimeDimensionResponse
  - `results` MetricWithAssociatedTimeDimension[], required
    - `fieldType` 'metric', required
    - `type` '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', required
    - `name` string, required
    - `label` string, required
    - `table` string, required
    - `tableLabel` string, required
    - `sql` string, required
    - `description` string
    - `source` Source
      - `content` string, required
      - `highlight` object
        - `end` SourcePosition, required
          - `character` number, double, required
          - `line` number, double, required
        - `start` SourcePosition, required
          - `character` number, double, required
          - `line` number, double, required
      - `range` object, required
        - `end` SourcePosition, required
          - `character` number, double, required
          - `line` number, double, required
        - `start` SourcePosition, required
          - `character` number, double, required
          - `line` number, double, required
      - `path` string, required
    - `hidden` boolean, required
    - `compact` union
      - 'auto' | 'thousands' | 'millions' | 'billions' | 'trillions' | 'kilobytes' | 'megabytes' | 'gigabytes' | 'terabytes' | 'petabytes' | 'kibibytes' | 'mebibytes' | 'gibibytes' | 'tebibytes' | 'pebibytes'
      - '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'
    - `round` number, double
    - `format` union
      - 'km' | 'mi' | 'si' | 'usd' | 'gbp' | 'eur' | 'jpy' | 'dkk' | 'id' | 'percent'
      - string
    - `separator` 'default' | 'commaPeriod' | 'spacePeriod' | 'periodComma' | 'noSeparatorPeriod' | 'apostrophePeriod'
    - `groupLabel` string
    - `groups` string[]
    - `urls` FieldUrl[]
      - `label` string, required
      - `url` string, required
    - `index` number, double
    - `tags` string[]
    - `parameterReferences` string[]
    - `showUnderlyingValues` string[]
    - `filters` MetricFilterRule[]
      - `includeNull` boolean — For the `equals` operator on string fields, also match rows where the field is null (compiles to `field IN (...) OR field IS NULL`). Lets users combine null with selected values in a single "is" rule.
      - `values` AnyType[] — Values to filter by
        - unknown
      - `operator` 'isNull' | 'notNull' | 'equals' | 'notEquals' | 'startsWith' | 'endsWith' | 'include' | 'doesNotInclude' | 'lessThan' | 'lessThanOrEqual' | 'greaterThan' | 'greaterThanOrEqual' | 'inThePast' | 'notInThePast' | 'inTheNext' | 'inTheCurrent' | 'notInTheCurrent' | 'inBetween' | 'notInBetween' | 'inPeriodToDate', required
      - `id` string, required — Unique identifier for the filter
      - `target` object, required — Target field for the filter
        - `fieldRef` string, required — Field reference to filter on (e.g., 'table_name.field_name')
      - `settings` unknown
      - `disabled` boolean — Whether this filter is disabled
      - `required` boolean — Whether this filter is required
      - `caseSensitive` boolean — 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.
    - `percentile` number, double
    - `distinctKeys` string[]
    - `formatOptions` CustomFormat
      - `type` 'default' | 'percent' | 'currency' | 'number' | 'id' | 'date' | 'timestamp' | 'bytes_si' | 'bytes_iec' | 'custom', required
      - `round` number, double — Number of decimal places
      - `separator` 'default' | 'commaPeriod' | 'spacePeriod' | 'periodComma' | 'noSeparatorPeriod' | 'apostrophePeriod'
      - `currency` string — Currency code (e.g., USD, GBP, EUR)
      - `compact` union
        - 'auto' | 'thousands' | 'millions' | 'billions' | 'trillions' | 'kilobytes' | 'megabytes' | 'gigabytes' | 'terabytes' | 'petabytes' | 'kibibytes' | 'mebibytes' | 'gibibytes' | 'tebibytes' | 'pebibytes'
        - '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'
      - `prefix` string — Prefix to prepend to formatted values
      - `suffix` string — Suffix to append to formatted values
      - `timeInterval` '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'
      - `custom` string — Custom format string
    - `dimensionReference` string
    - `baseDimensionType` 'string' | 'number' | 'timestamp' | 'date' | 'boolean'
    - `baseDimensionTimeInterval` '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'
    - `requiredAttributes` RecordStringStringOrStringArray — Construct a type with a set of properties K of type T
    - `anyAttributes` RecordStringStringOrStringArray — Construct a type with a set of properties K of type T
    - `defaultTimeDimension` DefaultTimeDimension
      - `interval` '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', required
      - `field` string, required
    - `spotlight` object
      - `owner` string
      - `defaultFilter` MetricFilterRule — Filter rule for metrics, targeting fields by reference
        - `includeNull` boolean — For the `equals` operator on string fields, also match rows where the field is null (compiles to `field IN (...) OR field IS NULL`). Lets users combine null with selected values in a single "is" rule.
        - `values` AnyType[] — Values to filter by
          - unknown
        - `operator` 'isNull' | 'notNull' | 'equals' | 'notEquals' | 'startsWith' | 'endsWith' | 'include' | 'doesNotInclude' | 'lessThan' | 'lessThanOrEqual' | 'greaterThan' | 'greaterThanOrEqual' | 'inThePast' | 'notInThePast' | 'inTheNext' | 'inTheCurrent' | 'notInTheCurrent' | 'inBetween' | 'notInBetween' | 'inPeriodToDate', required
        - `id` string, required — Unique identifier for the filter
        - `target` object, required — Target field for the filter
          - `fieldRef` string, required — Field reference to filter on (e.g., 'table_name.field_name')
        - `settings` unknown
        - `disabled` boolean — Whether this filter is disabled
        - `required` boolean — Whether this filter is required
        - `caseSensitive` boolean — 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.
      - `defaultSegment` string
      - `segmentBy` string[]
      - `filterBy` string[]
      - `categories` string[]
      - `visibility` 'show' | 'hide', required
    - `drivers` string[]
    - `aiHint` union
      - string
      - string[]
    - `richText` string
    - `compiledTimestampFilters` CompiledMetricTimestampFilter[]
      - `compiledSql` string, required
      - `fieldId` string, required
      - `id` string, required
    - `compiledRelativeDateFilters` CompiledMetricRelativeDateFilter[]
      - `compiledSql` string, required
      - `fieldId` string, required
      - `id` string, required
    - `compiledDistinctKeys` string[]
    - `compiledValueSql` string
    - `compilationError` FieldCompilationError — Error information stored on a field when compilation fails but partial compilation mode is enabled.
      - `message` string, required
    - `tablesAnyAttributes` RecordStringRecordStringStringOrStringArray — Construct a type with a set of properties K of type T
    - `tablesRequiredAttributes` RecordStringRecordStringStringOrStringArray — Construct a type with a set of properties K of type T
    - `tablesReferences` string[]
    - `compiledSql` string, required
    - `availableTimeDimensions` object[]
      - `fieldType` 'dimension', required
      - `type` union, required
        - 'date'
        - 'timestamp'
      - `name` string, required
      - `label` string, required
      - `table` string, required
      - `tableLabel` string, required
      - `sql` string, required
      - `description` string
      - `source` Source
        - `content` string, required
        - `highlight` object
          - `end` SourcePosition, required
            - `character` number, double, required
            - `line` number, double, required
          - `start` SourcePosition, required
            - `character` number, double, required
            - `line` number, double, required
        - `range` object, required
          - `end` SourcePosition, required
            - `character` number, double, required
            - `line` number, double, required
          - `start` SourcePosition, required
            - `character` number, double, required
            - `line` number, double, required
        - `path` string, required
      - `hidden` boolean, required
      - `compact` union
        - 'auto' | 'thousands' | 'millions' | 'billions' | 'trillions' | 'kilobytes' | 'megabytes' | 'gigabytes' | 'terabytes' | 'petabytes' | 'kibibytes' | 'mebibytes' | 'gibibytes' | 'tebibytes' | 'pebibytes'
        - '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'
      - `round` number, double
      - `format` union
        - 'km' | 'mi' | 'si' | 'usd' | 'gbp' | 'eur' | 'jpy' | 'dkk' | 'id' | 'percent'
        - string
      - `separator` 'default' | 'commaPeriod' | 'spacePeriod' | 'periodComma' | 'noSeparatorPeriod' | 'apostrophePeriod'
      - `groupLabel` string
      - `groups` string[]
      - `urls` FieldUrl[]
        - `label` string, required
        - `url` string, required
      - `index` number, double
      - `tags` string[]
      - `parameterReferences` string[]
      - `group` string
      - `requiredAttributes` RecordStringStringOrStringArray — Construct a type with a set of properties K of type T
      - `anyAttributes` RecordStringStringOrStringArray — Construct a type with a set of properties K of type T
      - `timeInterval` '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'
      - `timeIntervalLabel` string — Overridden display label for this dimension's grain (project `granularity_labels`); undefined when no override — callers fall back to `timeFrameConfigs[timeInterval].getLabel()`.
      - `timeIntervalBaseDimensionName` string
      - `timeIntervalBaseDimensionType` 'string' | 'number' | 'timestamp' | 'date' | 'boolean'
      - `customTimeInterval` string
      - `isAdditionalDimension` boolean
      - `skipTimezoneConversion` boolean
      - `timestampDomain` 'aware' | 'naive' — Whether a TIMESTAMP column stores an instant ('aware') or a bare wall clock ('naive'). Absent means unknown — never assume 'aware' for a missing value.
      - `colors` RecordStringString — Construct a type with a set of properties K of type T
      - `isIntervalBase` boolean
      - `aiHint` union
        - string
        - string[]
      - `formatOptions` CustomFormat
        - `type` 'default' | 'percent' | 'currency' | 'number' | 'id' | 'date' | 'timestamp' | 'bytes_si' | 'bytes_iec' | 'custom', required
        - `round` number, double — Number of decimal places
        - `separator` 'default' | 'commaPeriod' | 'spacePeriod' | 'periodComma' | 'noSeparatorPeriod' | 'apostrophePeriod'
        - `currency` string — Currency code (e.g., USD, GBP, EUR)
        - `compact` union
          - 'auto' | 'thousands' | 'millions' | 'billions' | 'trillions' | 'kilobytes' | 'megabytes' | 'gigabytes' | 'terabytes' | 'petabytes' | 'kibibytes' | 'mebibytes' | 'gibibytes' | 'tebibytes' | 'pebibytes'
          - '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'
        - `prefix` string — Prefix to prepend to formatted values
        - `suffix` string — Suffix to append to formatted values
        - `timeInterval` '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'
        - `custom` string — Custom format string
      - `caseSensitive` boolean
      - `image` object
        - `fit` string
        - `height` number, double
        - `width` number, double
        - `url` string, required
      - `richText` string
      - `filterAutocomplete` FilterAutocompleteConfig
        - `labelDimension` string
        - `fetchFromWarehouse` boolean, required
        - `values` FilterAutocompleteValue[]
          - `label` string
          - `value` string, required
      - `spotlight` object
        - `segmentBy` boolean
        - `filterBy` boolean
      - `compiledTimestampFilters` CompiledMetricTimestampFilter[]
        - `compiledSql` string, required
        - `fieldId` string, required
        - `id` string, required
      - `compiledRelativeDateFilters` CompiledMetricRelativeDateFilter[]
        - `compiledSql` string, required
        - `fieldId` string, required
        - `id` string, required
      - `compiledDistinctKeys` string[]
      - `compiledValueSql` string
      - `compilationError` FieldCompilationError — Error information stored on a field when compilation fails but partial compilation mode is enabled.
        - `message` string, required
      - `tablesAnyAttributes` RecordStringRecordStringStringOrStringArray — Construct a type with a set of properties K of type T
      - `tablesRequiredAttributes` RecordStringRecordStringStringOrStringArray — Construct a type with a set of properties K of type T
      - `tablesReferences` string[]
      - `compiledSql` string, required
    - `timeDimension` object
      - `interval` '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', required
      - `field` string, required
      - `table` string, required
  - `status` 'ok', required

## Other responses

- `default` — Error

---

[API](https://skmtc.dev/lightdash/apis/lightdash-api.md) · [All operations](https://skmtc.dev/lightdash/apis/lightdash-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/lightdash/lightdash-api/revisions/40c933755c9a/schema)