Skip to main content
Use replace mode when your application needs to deploy a revised dashboard to an existing dashboard ID. For example, you can maintain an operations dashboard in staging, export the approved revision, and replace the production dashboard’s contents without creating a new dashboard record. Call the Import Dashboard API with mode: "replace", the target workspaceName, the target external dashboardId, and the export’s data object as importDashboardData.
Replacement overwrites the dashboard’s base metrics, dashboard filters, and layout. Local changes to those parts of the target are replaced by the imported version. Export the target first so you have a recovery copy.

​
What changes

Replacing a dashboard does not update every client dashboard that was previously copied from it. Each target is a separate import operation.

​
Before you start

You need:
  • A company-level service token, stored on your backend.
  • An existing target dashboard and its external dashboard ID in the target workspace.
  • A target workspace in the token’s company, connected to the intended datasource or datamart.
  • A complete dashboard export with eligible metrics and their dependencies.
To create a dashboard for the first time, use the import endpoint with mode omitted. The only supported explicit mode value is lowercase "replace"; there is no "create", "merge", or "append" value.

​
Deploy a dashboard revision

1

Export the source revision and back up the target

Use the Export Dashboard API to save both the revised source and the current target as separate JSON files. Keep the source revision file with your application release.Exported files contain metadata and a data object. The import request uses the data object. If you export a client-specific view with sourceClientId, review the exported metrics and layout before using it as a replacement source.
2

Prepare the replacement request

Set dashboardId to the existing target’s external ID, not the source dashboard’s ID or an internal UUID. The API resolves the target within workspaceName.This example reads a complete export file using jq:
If the target uses different schema names, add schemaPairs to the request. Schema mapping rewrites imported references; it does not create tables or migrate warehouse data.
3

Replace the target from your backend

Send the request with your service token:
Submit replacements sequentially for each target dashboard. A missing target returns an error; replace mode does not create one automatically.
4

Check the import result and the dashboard

Require data.response in the response. Check top-level error and data.error: an import-stage error can arrive with HTTP 200. Review data.response.importSummary for skipped metrics.Open the target and verify its metric list, dashboard filters, saved metric filters, layout, and query results. Check merged cards, summary or expression cards, and chart-click actions if your dashboard uses them. Refresh integrations that cache metric IDs or filter definitions.

​
Limits and recovery

​
Full content replacement

The import replaces the base content rather than applying a partial update. It does not append metrics to the existing set or preserve local filter and layout edits. A payload with no eligible metrics returns an error; this feature is not a way to empty a dashboard.

​
Metric IDs, saved layouts, and scheduled reports

Imported metrics receive new IDs even when the same export is imported again. References inside the imported configuration are remapped where supported, but saved client-specific layouts, existing schedules, and external integrations are not migrated to the new metric IDs. Scheduled reports referencing old metrics keep those metrics alive and can continue to use the previous definitions. Review report configuration separately. Saved client layouts can still contain old metric references; verify the dashboard from the affected client views as well as the base view.

​
Client ownership

This workspace endpoint does not accept a destination clientId or cross-client import controls and does not derive metric ownership from the replacement target. Replacement preserves the target’s existing ownership fields, while imported metric ownership can come from the export. It is not a cross-client rebinding operation. Use a workspace-authored dashboard and source export for a base-dashboard release workflow. If you need to provision a new client dashboard and bind imported metrics to a destination client, use Create Dashboard Embed. Replacing a client-owned target with another client’s export can leave the imported metrics unavailable to the intended viewer.

​
Concurrency and failed imports

The endpoint does not provide a per-dashboard lock or revision check. Two replacements running at once can leave mixed metric associations or overwrite each other’s dashboard fields. Coordinate replacements in your application so only one runs at a time for each target. New metrics are prepared before old links are removed. On a failed replacement, the importer attempts to remove newly inserted metrics and restore changed dashboard fields. Recovery and orphan cleanup are best-effort operations, rather than one database transaction. After an error, inspect the target before retrying. Keep your export backup; reimporting it also creates new metric IDs and does not restore external references to the original metrics.