> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usedatabrain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Export Dashboard

> Export a dashboard from a workspace as a JSON file for backup, migration, or import into another workspace.

Export a dashboard and its configuration (layout, metrics, filters) from a workspace. The response is a JSON file download that can be used with the [Import Dashboard API](/developer-docs/helpers/api-reference/import-dashboard) or the UI import flow.

<Warning>
  **Authentication Requirement:** This endpoint requires a **service token** (company-level), not a data app API key. Service tokens have elevated permissions. Use the token that has access to the workspace and dashboard.
</Warning>

## Authentication

Use your service token in the `Authorization` header. See [Create Service Token](/developer-docs/helpers/api-reference/create-service-token) for how to obtain a service token.

<Panel>
  <RequestExample>
    ```bash Authentication theme={"dark"}
    curl --request POST \
      --url https://api.usedatabrain.com/api/v2/data-app/export-dashboard \
      --header 'Authorization: Bearer YOUR_SERVICE_TOKEN' \
      --header 'Content-Type: application/json' \
      --data '{"dashboardId":"your-dashboard-id","workspaceName":"Your Workspace"}'
    ```
  </RequestExample>
</Panel>

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for API authentication. Use your **service token** (company-level).

  ```
  Authorization: Bearer dbn_live_...
  ```
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json` when sending a JSON body.

  ```
  Content-Type: application/json
  ```
</ParamField>

## Request Body

<ParamField body="dashboardId" type="string" required>
  The dashboard ID to export. This is the external dashboard ID (e.g. from [Fetch Dashboards by Data App](/developer-docs/helpers/api-reference/fetch-dashboards-by-datapp) or the dashboard list in the UI).
</ParamField>

<ParamField body="workspaceName" type="string" required>
  The name of the workspace that contains the dashboard. Must match the workspace name exactly.
</ParamField>

## Response

On success, the API returns **200** with:

* **Content-Type:** `application/json`
* **Content-Disposition:** `attachment; filename="dashboard-{dashboardId}.json"`

The response body is a JSON object with this structure:

<ResponseField name="_meta" type="object">
  Metadata about the export.

  <ResponseField name="_meta.exportedAt" type="string">
    ISO 8601 timestamp when the export was performed.
  </ResponseField>

  <ResponseField name="_meta.workspaceName" type="string">
    The workspace name the dashboard was exported from.
  </ResponseField>

  <ResponseField name="_meta.dashboardId" type="string">
    The dashboard ID that was exported.
  </ResponseField>
</ResponseField>

<ResponseField name="data" type="object">
  The dashboard configuration and content (layout, metrics, filters, etc.). Structure matches what the import API expects as `importDashboardData`.
</ResponseField>

On error, the API returns a JSON error object (e.g. 400 or 500) with `error.code` and `error.message`.

## Examples

<Panel>
  <RequestExample>
    ```bash cURL theme={"dark"}
    curl --request POST \
      --url 'https://api.usedatabrain.com/api/v2/data-app/export-dashboard' \
      --header 'Authorization: Bearer dbn_live_...' \
      --header 'Content-Type: application/json' \
      --data '{"dashboardId":"sales-dashboard-1","workspaceName":"Sales Workspace"}' \
      --output dashboard-sales-dashboard-1.json
    ```

    ```javascript Node.js icon="fa-brands fa-node-js" theme={"dark"}
    const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/export-dashboard', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer dbn_live_...',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        dashboardId: 'sales-dashboard-1',
        workspaceName: 'Sales Workspace'
      })
    });

    if (!response.ok) {
      const err = await response.json();
      throw new Error(err.error?.message || 'Export failed');
    }

    const blob = await response.blob();
    // Save or process the JSON file
    const text = await blob.text();
    const exported = JSON.parse(text);
    console.log('Exported at:', exported._meta?.exportedAt);
    ```

    ```python Python icon="fa-brands fa-python" theme={"dark"}
    import requests

    url = "https://api.usedatabrain.com/api/v2/data-app/export-dashboard"
    headers = {
        "Authorization": "Bearer dbn_live_...",
        "Content-Type": "application/json"
    }
    payload = {
        "dashboardId": "sales-dashboard-1",
        "workspaceName": "Sales Workspace"
    }

    response = requests.post(url, headers=headers, json=payload)

    if not response.ok:
        raise Exception(response.json().get("error", {}).get("message", "Export failed"))

    with open("dashboard-sales-dashboard-1.json", "w") as f:
        f.write(response.text)
    ```
  </RequestExample>

  <ResponseExample>
    ```json Success (response body is the downloaded JSON) theme={"dark"}
    {
      "_meta": {
        "exportedAt": "2025-02-13T10:00:00.000Z",
        "workspaceName": "Sales Workspace",
        "dashboardId": "sales-dashboard-1"
      },
      "data": {
        "layout": [...],
        "filters": [...],
        ...
      }
    }
    ```

    ```json Error Response (400) theme={"dark"}
    {
      "error": {
        "code": "INVALID_REQUEST_BODY",
        "message": "\"dashboardId\" is required"
      }
    }
    ```

    ```json Error Response (400) theme={"dark"}
    {
      "error": {
        "code": "AUTH_ERROR",
        "message": "Invalid Service Token"
      }
    }
    ```

    ```json Error Response (400) theme={"dark"}
    {
      "error": {
        "code": "DATA_APP_NOT_FOUND",
        "message": "Data app not found"
      }
    }
    ```
  </ResponseExample>
</Panel>

## HTTP Status Code Summary

| Status Code | Description                                                                                      |
| ----------- | ------------------------------------------------------------------------------------------------ |
| `200`       | **OK** – Dashboard exported successfully; response is a JSON file (attachment)                   |
| `400`       | **Bad Request** – Invalid or missing parameters, invalid token, or dashboard/workspace not found |
| `500`       | **Internal Server Error** – Server error during export                                           |

## Possible Errors

| Code                    | Message                                                   | HTTP Status |
| ----------------------- | --------------------------------------------------------- | ----------- |
| `INVALID_REQUEST_BODY`  | Joi validation message (e.g. `"dashboardId" is required`) | 400         |
| `AUTH_ERROR`            | Invalid Service Token                                     | 400         |
| `DATA_APP_NOT_FOUND`    | Data app not found                                        | 400         |
| `INTERNAL_SERVER_ERROR` | Server error message                                      | 500         |

## Related

* [Import Dashboard](/developer-docs/helpers/api-reference/import-dashboard) – Import a previously exported dashboard into a workspace
* [Fetch Dashboards by Data App](/developer-docs/helpers/api-reference/fetch-dashboards-by-datapp) – List dashboards to get `dashboardId` values
* [Import/Export Dashboard (UI)](/guides/dashboards/import-export-dashboard) – UI guide for import/export