---
title: "Get dashboard promotion diff"
method: GET
path: "/api/v1/dashboards/{dashboardUuidOrSlug}/promoteDiff"
tags: ["Dashboards"]
---

# Get dashboard promotion diff

`GET /api/v1/dashboards/{dashboardUuidOrSlug}/promoteDiff`

Get diff from dashboard to promote

## Path parameters

- `dashboardUuidOrSlug` string, required — A resource UUID or its URL slug. Resolve to a real UUID before using as a key.

## Query parameters

- `projectUuid` string, uuid — Stringified UUIDv4. See [RFC 4112](https://tools.ietf.org/html/rfc4122)

## Response `200`

Success

- ApiPromotionChangesResponse
  - `results` PromotionChanges, required
    - `dataApps` object[]
      - `data` PromotedApp, required
        - `name` string, required
        - `uuid` string, required
      - `action` 'no changes' | 'create' | 'update' | 'delete', required
    - `sqlCharts` object[]
      - `data` PromotedSqlChart, required
        - `spacePath` string, required
        - `spaceSlug` string, required
        - `description` string, nullable, required
        - `name` string, required
        - `projectUuid` string, required
        - `slug` string, required
        - `oldUuid` string, required
        - `uuid` string, required
      - `action` 'no changes' | 'create' | 'update' | 'delete', required
    - `charts` object[], required
      - `data` PromotedChart, required — From T, pick a set of properties whose keys are in the union K
        - `name` string, required — Display name of the chart
        - `description` string — Optional description of what this chart displays
        - `tableName` string, required — The explore/table name this chart queries from
        - `metricQuery` MetricQuery, required
          - `metadata` object
            - `hasADateDimension` PickCompiledDimensionLabelOrNameOrTable, required — From T, pick a set of properties whose keys are in the union K
              - …
          - `pivotDimensions` FieldId[] — Dimension field IDs used as pivot columns (from chart's pivotConfig.columns). Used by row_total() to determine non-pivot dimensions for GROUP BY.
          - `timezone` string — Timezone for date/time values (e.g., 'America/Los_Angeles', 'UTC')
          - `dimensionOverrides` DimensionOverrides
          - `metricOverrides` MetricOverrides
          - `customDimensions` CustomDimension[] — Custom dimensions defined inline
            - union
              - …
          - `additionalMetrics` AdditionalMetric[] — Custom metrics defined inline (ad-hoc metrics not in the dbt model)
            - `label` string — Display label for the metric
            - `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
            - `description` string — Description of what the metric measures
            - `sql` string, required — SQL expression (e.g., ${TABLE}.column_name)
            - `hidden` boolean — Whether the metric is hidden from users
            - `round` number, double — Number of decimal places
            - `compact` union
              - …
            - `format` union — Format string (legacy format specification)
              - …
            - `separator` 'default' | 'commaPeriod' | 'spacePeriod' | 'periodComma' | 'noSeparatorPeriod' | 'apostrophePeriod'
            - `table` string, required — Table name the metric belongs to
            - `name` string, required — Internal name of the metric
            - `index` number, double — Display order index
            - `filters` MetricFilterRule[] — Filters to apply to this metric
              - …
            - `baseDimensionName` string — Name of the base dimension/column this metric aggregates
            - `baseMetricName` string — Name of the explore metric this metric was cloned from
            - `uuid` string, nullable — Unique identifier for the metric
            - `percentile` number, double — Percentile value for percentile metrics
            - `distinctKeys` string[]
            - `formatOptions` CustomFormat
              - …
            - `generationType` 'periodOverPeriod' — Optional marker for metrics generated by the system. Currently used for Period-over-Period (PoP) previous-period metrics.
            - `baseMetricId` string
            - `timeDimensionId` string
            - `granularity` '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'
            - `periodOffset` number, double — For PoP-generated metrics, the number of periods to offset by (>= 1).
          - `tableCalculations` TableCalculation[], required — Custom calculations to perform on query results
            - union
              - …
          - `limit` number, double, required — Maximum number of rows to return
          - `sorts` SortField[], required — Sort configuration for query results
            - `pivotValues` PivotSortAnchor[] — Pins the row-sort anchor to a specific pivot column. Ignored for non-pivoted results.
              - …
            - `nullsFirst` boolean — Sort null values first
            - `descending` boolean, required — Sort in descending order
            - `fieldId` string, required — Field ID to sort by
          - `filters` Filters, required
            - `tableCalculations` union
              - …
            - `metrics` union
              - …
            - `dimensions` union
              - …
          - `metrics` FieldId[], required — List of metric field IDs to include
          - `dimensions` FieldId[], required — List of dimension field IDs to include
          - `exploreName` string, required — The name of the explore to query
        - `chartConfig` union, required
          - BigNumberConfig
            - `config` BigNumber
              - …
            - `type` 'big_number', required
          - CartesianChartConfig
            - `config` CartesianChart
              - …
            - `type` 'cartesian', required
          - CustomVisConfig
            - `config` CustomVis
              - …
            - `type` 'custom', required
          - PieChartConfig
            - `config` PieChart
              - …
            - `type` 'pie', required
          - FunnelChartConfig
            - `config` FunnelChart
              - …
            - `type` 'funnel', required
          - TableChartConfig
            - `config` TableChart
              - …
            - `type` 'table', required
          - TreemapChartConfig
            - `config` TreemapChart
              - …
            - `type` 'treemap', required
          - GaugeChartConfig
            - `config` GaugeChart
              - …
            - `type` 'gauge', required
          - DataAppVizChartConfig
            - `config` DataAppVizChart
              - …
            - `type` 'data_app_viz', required
          - MapChartConfig
            - `config` MapChart
              - …
            - `type` 'map', required
          - SankeyChartConfig
            - `config` SankeyChart
              - …
            - `type` 'sankey', required
        - `pivotConfig` object — Pivot table configuration
          - `rows` string[]
          - `columns` string[], required
        - `slug` string, required — Unique identifier slug for this chart
        - `parameters` ParametersValuesMap — Construct a type with a set of properties K of type T
        - `uuid` string, required
        - `organizationUuid` string, required
        - `projectUuid` string, required
        - `pinnedListUuid` string, nullable, required
        - `pinnedListOrder` number, double, nullable, required
        - `verification` ContentVerificationInfo, required
          - `verifiedAt` string, date-time, required
          - `verifiedBy` object, required
            - `lastName` string, required
            - `firstName` string, required
            - `userUuid` string, required
        - `updatedAt` string, date-time, required — Timestamp when the chart was last updated
        - `updatedByUser` UpdatedByUser
          - `userUuid` string, required
          - `firstName` string, required
          - `lastName` string, required
        - `spaceUuid` string, required
        - `spaceName` string, required
        - `colorPaletteUuid` string, nullable, required — Chart-level palette override pointer. `null` means inherit from the containing dashboard / space / project / org. Writable via `UpdateSavedChart`.
        - `deletedAt` string, date-time
        - `deletedBy` object, nullable
          - `lastName` string, required
          - `firstName` string, required
          - `userUuid` string, required
        - `tableConfig` object, required — Table view configuration
          - `columnOrder` string[], required
        - `dashboardUuid` string, nullable, required
        - `dashboardName` string, nullable, required
        - `colorPalette` string[], required
        - `resolvedColorPalette` ResolvedProjectColorPalette, required
          - `source` union, required — Where a resolved colour palette came from. The `config` and `default` cases carry no entity reference; the rest expose the UUID and human-readable name of the entity (organization, project, space, dashboard or chart) that owns the winning palette in the resolution chain.
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
          - `paletteName` string, nullable, required
          - `paletteUuid` string, nullable, required
          - `darkColors` string[], nullable, required
          - `colors` string[], required
        - `oldUuid` string, required
        - `spacePath` string, required
        - `spaceSlug` string, required
      - `action` 'no changes' | 'create' | 'update' | 'delete', required
    - `dashboards` object[], required
      - `data` PromotedDashboard, required — From T, pick a set of properties whose keys are in the union K
        - `name` string, required
        - `description` string
        - `slug` string, required
        - `parameters` DashboardParameters — Construct a type with a set of properties K of type T
        - `filters` DashboardFilters, required
          - `tableCalculations` DashboardFilterRule[], required
            - `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
              - …
            - `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` DashboardFieldTarget, required
              - …
            - `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.
            - `lockedTabUuids` string[] — Tab UUIDs where this filter is locked. When the active tab is in this list, viewers see the filter but cannot change it, and URL / embed filter overrides targeting the same field are ignored on that tab. Empty or omitted means the filter is not locked anywhere.
            - `requiredGroupId` string — Dashboard filters sharing a requiredGroupId form an "any-one required" group: the dashboard is locked until at least one member has a value.
            - `singleValue` boolean
            - `label` string
            - `tileTargets` DashboardTileTargets — Deliberately an index-signature literal, not `Record<string, ...>`. When TSOA first resolves `Record<string, DashboardTileTarget>` inside a mapped type (e.g. `Omit<DashboardFilterRule, 'id'>` in content-as-code types), it caches an EMPTY model under the shared `Record_string.DashboardTileTarget_` name, and request validation then strips every tileTargets entry from bodies — silently breaking dashboard filters on SQL chart tiles. The index-signature form resolves correctly in every context.
          - `metrics` DashboardFilterRule[], required
            - `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
              - …
            - `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` DashboardFieldTarget, required
              - …
            - `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.
            - `lockedTabUuids` string[] — Tab UUIDs where this filter is locked. When the active tab is in this list, viewers see the filter but cannot change it, and URL / embed filter overrides targeting the same field are ignored on that tab. Empty or omitted means the filter is not locked anywhere.
            - `requiredGroupId` string — Dashboard filters sharing a requiredGroupId form an "any-one required" group: the dashboard is locked until at least one member has a value.
            - `singleValue` boolean
            - `label` string
            - `tileTargets` DashboardTileTargets — Deliberately an index-signature literal, not `Record<string, ...>`. When TSOA first resolves `Record<string, DashboardTileTarget>` inside a mapped type (e.g. `Omit<DashboardFilterRule, 'id'>` in content-as-code types), it caches an EMPTY model under the shared `Record_string.DashboardTileTarget_` name, and request validation then strips every tileTargets entry from bodies — silently breaking dashboard filters on SQL chart tiles. The index-signature form resolves correctly in every context.
          - `dimensions` DashboardFilterRule[], required
            - `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
              - …
            - `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` DashboardFieldTarget, required
              - …
            - `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.
            - `lockedTabUuids` string[] — Tab UUIDs where this filter is locked. When the active tab is in this list, viewers see the filter but cannot change it, and URL / embed filter overrides targeting the same field are ignored on that tab. Empty or omitted means the filter is not locked anywhere.
            - `requiredGroupId` string — Dashboard filters sharing a requiredGroupId form an "any-one required" group: the dashboard is locked until at least one member has a value.
            - `singleValue` boolean
            - `label` string
            - `tileTargets` DashboardTileTargets — Deliberately an index-signature literal, not `Record<string, ...>`. When TSOA first resolves `Record<string, DashboardTileTarget>` inside a mapped type (e.g. `Omit<DashboardFilterRule, 'id'>` in content-as-code types), it caches an EMPTY model under the shared `Record_string.DashboardTileTarget_` name, and request validation then strips every tileTargets entry from bodies — silently breaking dashboard filters on SQL chart tiles. The index-signature form resolves correctly in every context.
        - `tabs` DashboardTab[], required
          - `hidden` boolean
          - `order` number, double, required
          - `name` string, required
          - `uuid` string, required
        - `config` DashboardConfig
          - `requiredFiltersNote` string — Editor-authored note shown to viewers while filter rules are unmet
          - `dateZoomConfig` DateZoomConfig
            - `tileTargets` RecordStringDateZoomTileTarget, required — Construct a type with a set of properties K of type T
            - `controls` DateZoomControl[], required
              - …
          - `defaultDateZoomGranularity` union
            - 'Second' | 'Minute' | 'Hour' | 'Day' | 'Week' | 'Month' | 'Quarter' | 'Year'
            - string
          - `dateZoomGranularities` union[]
            - union
              - …
          - `parameterOrder` string[]
          - `pinnedParameters` string[]
          - `isAddFilterDisabled` boolean
          - `isDateZoomDisabled` boolean, required
        - `uuid` string, required
        - `organizationUuid` string, required
        - `projectUuid` string, required
        - `pinnedListUuid` string, nullable, required
        - `pinnedListOrder` number, double, nullable, required
        - `dashboardVersionId` number, double, required
        - `versionUuid` string, required
        - `verification` ContentVerificationInfo, required
          - `verifiedAt` string, date-time, required
          - `verifiedBy` object, required
            - `lastName` string, required
            - `firstName` string, required
            - `userUuid` string, required
        - `updatedAt` string, date-time, required
        - `tiles` DashboardTile[], required
          - union
            - DashboardChartTile — Make all properties in T required
              - …
            - DashboardMarkdownTile — Make all properties in T required
              - …
            - DashboardLoomTile — Make all properties in T required
              - …
            - DashboardSqlChartTile — Make all properties in T required
              - …
            - DashboardHeadingTile — Make all properties in T required
              - …
            - DashboardDataAppTile — Make all properties in T required
              - …
        - `updatedByUser` UpdatedByUser
          - `userUuid` string, required
          - `firstName` string, required
          - `lastName` string, required
        - `spaceUuid` string, required
        - `spaceName` string, required
        - `views` number, double, required
        - `firstViewedAt` union, required
          - string
          - string, date-time
        - `colorPaletteUuid` string, nullable, required
        - `deletedAt` string, date-time
        - `deletedBy` object, nullable
          - `lastName` string, required
          - `firstName` string, required
          - `userUuid` string, required
        - `spacePath` string, required
        - `spaceSlug` string, required
      - `action` 'no changes' | 'create' | 'update' | 'delete', required
    - `spaces` object[], required
      - `data` PromotedSpace, required — From T, pick a set of properties whose keys are in the union K
        - `name` string, required
        - `slug` string, required
        - `uuid` string, required
        - `organizationUuid` string, required
        - `projectUuid` string, required
        - `inheritParentPermissions` boolean, required
        - `projectMemberAccessRole` 'viewer' | 'editor' | 'admin', required
        - `pinnedListUuid` string, nullable, required
        - `pinnedListOrder` number, double, nullable, required
        - `parentSpaceUuid` string, nullable, required
        - `path` string, required
        - `deletedBy` object
          - `lastName` string, required
          - `firstName` string, required
          - `userUuid` string, required
        - `deletedAt` string, date-time
        - `appCount` number, double, required
        - `childSpaceCount` number, double, required
        - `dashboardCount` number, double, required
        - `chartCount` number, double, required
      - `action` 'no changes' | 'create' | 'update' | 'delete', required
  - `status` 'ok', required

## Other responses

- `default` — Error

---

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