Data Retrieval
Import a dashboard
Make a new dashboard in a workspace from an exported dashboard file.
Databrain makes the dashboard with its metrics, filters and layout in the workspace you name.
curl --request POST https://api.usedatabrain.com/api/v2/data-app/import-dashboard \ --header "Authorization: Bearer $DATABRAIN_SERVICE_TOKEN" \ --header "Content-Type: application/json" \ --data "{ \"workspaceName\": \"Customer analytics EU\", \"dashboardId\": \"sales-overview-eu\", \"schemaPairs\": [{ \"replaceSchema\": \"public\", \"targetSchema\": \"eu\" }], \"importDashboardData\": $(cat dashboard-sales-overview.json) }"Before you start
- You have a service token. See Authentication.
- You have a file from Export a dashboard.
- The workspace has a datasource or datamart with the tables the metrics use.
ServiceTokenAuthorizationBearer <token>A service token. A data app API token is refused.
Body
The workspace to import into.
The export file as it is, or only its data
Id of the new dashboard. Default: the exported id plus a time stamp.
<exported externalDashboardId>_<Date.now()>Name of the new dashboard. Default: the exported name.
Schema names to swap in the metrics' SQL: { "replaceSchema": "public", "targetSchema": "eu" }. Fill both or neither.
2 fields in schemaPairs
replace
Required to replace: the version from your dry run.
Response
{ "data": { "response": { "message": "Imported Dashboard with 8 metrics", "dashboardId": "sales-overview-eu", "dashboardName": "Sales overview", "workspaceName": "Customer analytics EU", "importSummary": { "imported": 8, "skipped": 1, "skippedMetrics": [{ "metricId": "...", "name": "Churn", "reason": "TARGET_TABLE_NOT_FOUND" }] } } }}A metric is skipped when the workspace cannot run it. reason says why, with the same values as on Create a customer dashboard embed.
If the import fails part way, you still get 200, with data.error instead of data.response, and part of the dashboard can stay. Check data.error on every call.
{ "data": { "error": { "message": "No data source or data mart is connected!", "hint": "..." } } }Replace a dashboard in place
Send "mode": "replace" to update an existing dashboard from the file, in a dry run first. It needs dashboard environments on for your organization (Settings > Environments), else 403 FEATURE_NOT_ENABLED.
The response is { "data": { "dashboardId", "version", "changes", "metrics", "checks", "warnings", "dryRun" } }. Any other mode value is ignored, and a normal import runs.
Errors
| Status | error.code | Why |
|---|---|---|
| 400 | INVALID_REQUEST_BODY | A field is missing or wrong |
| 400 | WORKSPACE_ID_ERROR | No workspace has this name |
| 400 | INVALID_DASHBOARD_ID | A dashboard in the workspace already has this dashboardId |
| 403 | AUTHENTICATION_ERROR | You used a data app API token |
| 403 | FEATURE_NOT_ENABLED | Replace: dashboard environments are off |
| 403 | FOREIGN_EXPORT | Replace: the file is from another organization |
| 404 | DASHBOARD_NOT_FOUND | Replace: no dashboard has this id |
| 400 | EXPECTED_VERSION_REQUIRED | Replace: run a dry run first and send its version |
| 409 | LIVE_CHANGED | Replace: the dashboard changed after your dry run |
| 500 | INTERNAL_SERVER_ERROR | The import failed |
For errors that every endpoint returns, see Authentication.
curl -X POST 'https://api.usedatabrain.com/api/v2/data-app/import-dashboard' \ -H 'Content-Type: application/json' \ -d '{ "workspaceName": "string", "importDashboardData": {}}'{ "data": { "dashboardId": "sales-overview", "version": "...", "changes": { "added": 0, "updated": 2, "retired": 0, "unchanged": 5 }, "metrics": [ { "source": "m1", "target": "m1", "action": "updated" } ], "checks": [], "warnings": [], "dryRun": true }}