Data Retrieval
Import Dashboard
Create a dashboard from an export, or replace an existing dashboard’s metrics, filters, and base layout while keeping its ID.
POST
Import the
data object from a dashboard export into a workspace. Omit mode to create a dashboard. Set mode: "replace" to replace the contents of an existing dashboard with the same dashboardId in that workspace.
For a deployment workflow and a field-by-field explanation of what changes, see Replace dashboard contents.
Authentication
Use a company-level service token in theAuthorization header. The target workspace must belong to the service token’s company. A Data App API key or guest token cannot be used for this operation.
Headers
Set to
application/json. Read an exported file and send its data object as importDashboardData in the JSON request body.Request body
Existing target workspace name in the service token’s company. The workspace must have a connected datasource or datamart, or a configured multi-datasource or multi-datamart setup.
The
data object from the Export Dashboard API or a UI-exported dashboard file. Use the complete export data, including its metrics and dashboard configuration. Do not send the enclosing export wrapper as this field.Joi validates this field as an object. The import also validates the exported content and requires eligible metrics; an empty object or a payload with no metrics cannot be used to clear a dashboard.Optional. The only accepted value is the exact lowercase string
"replace". Omit this field to create a new dashboard; "create", "merge", "append", and "REPLACE" are not accepted values.With "replace", dashboardId is required and must identify an existing dashboard in workspaceName. A missing target returns an import error; replace mode does not create it automatically.External dashboard ID in the target workspace, rather than its internal database UUID.
- Create: Optional. Sets the new dashboard’s external ID. If omitted, the import generates an ID. If the supplied ID already exists in the target workspace, the request fails with
INVALID_DASHBOARD_ID. - Replace: Required. Selects the existing target by external ID and workspace. The target keeps its external ID and internal dashboard record.
Optional display name. If omitted, the name from the export is used, including in replace mode. To keep the target’s previous name, provide it explicitly.
Optional schema mappings for the imported SQL and related configuration. Each item requires
replaceSchema and targetSchema, both strings. Strings are trimmed and may be empty; further schema-mapping checks run during the import.Schema mappings do not create warehouse tables, migrate data, or configure a new datasource. Verify that the mapped tables and columns exist in the target connection.Create and replace behavior
Imported metrics receive new IDs. References within the imported dashboard are remapped where supported; integrations, saved client layouts, and schedules that reference previous metric IDs are not automatically migrated. Old metrics still used by another dashboard or scheduled report are preserved; unreferenced old metrics are eligible for cleanup.
Request examples
These examples use the complete JSON file produced by the export API. The cURL examples usejq to extract its data object and build the request.
Response
Import result. On success, contains
response. Import-stage failures can instead contain error, even when the HTTP status is 200.Successful import details:
message, dashboardId, dashboardName, workspaceName, and importSummary.Includes
imported and skipped counts and a skippedMetrics array with details for skipped candidates. Review this summary and the resulting dashboard before marking a deployment complete.Import-stage error with a
message, and sometimes additional details. Check this field as well as top-level error and the HTTP status.Request-level failure with
code and message, such as invalid parameters, service-token context, or workspace resolution.Errors and recovery
The importer prepares new metrics before detaching the old ones. On a replacement failure it attempts to remove inserted metrics and, if dashboard fields were changed, restore the previous name, filters, layout, grid spacing, and filter layout. These recovery operations can also fail; the operation is not a single database transaction. Check the target after an error before retrying.
Send one replacement at a time for a given dashboard. The endpoint does not serialize overlapping replacements or provide a revision check. See the feature guide for client ownership, saved layouts, and schedule limitations.

