List All Embeds

curl --request GET \
  --url 'https://api.usedatabrain.com/api/v2/data-app/embeds?isPagination=true&pageNumber=1' \
  --header 'Authorization: Bearer dbn_live_abc123...'

{
  "data": [
    {
      "embedId": "dashboard-123",
      "embedType": "dashboard",
      "name": "Sales Dashboard Embed",
      "externalDashboard": {
        "externalDashboardId": "dashboard-uuid-456",
        "metadata": {
          "createdAt": "2024-01-15T10:30:00Z",
          "updatedAt": "2024-01-20T14:45:00Z"
        },
        "name": "Sales Analytics Dashboard"
      },
      "externalMetric": null,
      "embedMetadata": {
        "embedId": "dashboard-123",
        "name": "Sales Dashboard Embed",
        "embedType": "dashboard",
        "dataAppName": "Production Data App",
        "metricId": null,
        "dashboardId": "dashboard-uuid-456",
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-20T14:45:00Z"
      }
    },
    {
      "embedId": "metric-456",
      "embedType": "metric",
      "name": "Revenue Metric Embed",
      "externalDashboard": null,
      "externalMetric": {
        "metricId": "metric-uuid-789",
        "name": "Monthly Revenue"
      },
      "embedMetadata": {
        "embedId": "metric-456",
        "name": "Revenue Metric Embed",
        "embedType": "metric",
        "dataAppName": "Production Data App",
        "metricId": "metric-uuid-789",
        "dashboardId": null,
        "createdAt": "2024-01-16T08:15:00Z",
        "updatedAt": "2024-01-18T12:30:00Z"
      }
    }
  ],
  "error": null
}

curl --request GET \
  --url 'https://api.usedatabrain.com/api/v2/data-app/embeds?isPagination=true&pageNumber=1' \
  --header 'Authorization: Bearer dbn_live_abc123...'

{
  "data": [
    {
      "embedId": "dashboard-123",
      "embedType": "dashboard",
      "name": "Sales Dashboard Embed",
      "externalDashboard": {
        "externalDashboardId": "dashboard-uuid-456",
        "metadata": {
          "createdAt": "2024-01-15T10:30:00Z",
          "updatedAt": "2024-01-20T14:45:00Z"
        },
        "name": "Sales Analytics Dashboard"
      },
      "externalMetric": null,
      "embedMetadata": {
        "embedId": "dashboard-123",
        "name": "Sales Dashboard Embed",
        "embedType": "dashboard",
        "dataAppName": "Production Data App",
        "metricId": null,
        "dashboardId": "dashboard-uuid-456",
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-20T14:45:00Z"
      }
    },
    {
      "embedId": "metric-456",
      "embedType": "metric",
      "name": "Revenue Metric Embed",
      "externalDashboard": null,
      "externalMetric": {
        "metricId": "metric-uuid-789",
        "name": "Monthly Revenue"
      },
      "embedMetadata": {
        "embedId": "metric-456",
        "name": "Revenue Metric Embed",
        "embedType": "metric",
        "dataAppName": "Production Data App",
        "metricId": "metric-uuid-789",
        "dashboardId": null,
        "createdAt": "2024-01-16T08:15:00Z",
        "updatedAt": "2024-01-18T12:30:00Z"
      }
    }
  ],
  "error": null
}

curl --request GET \
  --url 'https://api.usedatabrain.com/api/v2/data-app/embeds?isPagination=true&pageNumber=1' \
  --header 'Authorization: Bearer dbn_live_abc123...'

{
  "data": [
    {
      "embedId": "dashboard-123",
      "embedType": "dashboard",
      "name": "Sales Dashboard Embed",
      "externalDashboard": {
        "externalDashboardId": "dashboard-uuid-456",
        "metadata": {
          "createdAt": "2024-01-15T10:30:00Z",
          "updatedAt": "2024-01-20T14:45:00Z"
        },
        "name": "Sales Analytics Dashboard"
      },
      "externalMetric": null,
      "embedMetadata": {
        "embedId": "dashboard-123",
        "name": "Sales Dashboard Embed",
        "embedType": "dashboard",
        "dataAppName": "Production Data App",
        "metricId": null,
        "dashboardId": "dashboard-uuid-456",
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-20T14:45:00Z"
      }
    },
    {
      "embedId": "metric-456",
      "embedType": "metric",
      "name": "Revenue Metric Embed",
      "externalDashboard": null,
      "externalMetric": {
        "metricId": "metric-uuid-789",
        "name": "Monthly Revenue"
      },
      "embedMetadata": {
        "embedId": "metric-456",
        "name": "Revenue Metric Embed",
        "embedType": "metric",
        "dataAppName": "Production Data App",
        "metricId": "metric-uuid-789",
        "dashboardId": null,
        "createdAt": "2024-01-16T08:15:00Z",
        "updatedAt": "2024-01-18T12:30:00Z"
      }
    }
  ],
  "error": null
}

GET

api

data-app

embeds

curl --request GET \
  --url 'https://api.usedatabrain.com/api/v2/data-app/embeds?isPagination=true&pageNumber=1' \
  --header 'Authorization: Bearer dbn_live_abc123...'

{
  "data": [
    {
      "embedId": "dashboard-123",
      "embedType": "dashboard",
      "name": "Sales Dashboard Embed",
      "externalDashboard": {
        "externalDashboardId": "dashboard-uuid-456",
        "metadata": {
          "createdAt": "2024-01-15T10:30:00Z",
          "updatedAt": "2024-01-20T14:45:00Z"
        },
        "name": "Sales Analytics Dashboard"
      },
      "externalMetric": null,
      "embedMetadata": {
        "embedId": "dashboard-123",
        "name": "Sales Dashboard Embed",
        "embedType": "dashboard",
        "dataAppName": "Production Data App",
        "metricId": null,
        "dashboardId": "dashboard-uuid-456",
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-20T14:45:00Z"
      }
    },
    {
      "embedId": "metric-456",
      "embedType": "metric",
      "name": "Revenue Metric Embed",
      "externalDashboard": null,
      "externalMetric": {
        "metricId": "metric-uuid-789",
        "name": "Monthly Revenue"
      },
      "embedMetadata": {
        "embedId": "metric-456",
        "name": "Revenue Metric Embed",
        "embedType": "metric",
        "dataAppName": "Production Data App",
        "metricId": "metric-uuid-789",
        "dashboardId": null,
        "createdAt": "2024-01-16T08:15:00Z",
        "updatedAt": "2024-01-18T12:30:00Z"
      }
    }
  ],
  "error": null
}

Get a comprehensive list of all embed configurations created by your data app, including both dashboard and metric embeds with their associated metadata.

Endpoint Migration Notice: We’re transitioning to kebab-case endpoints. The new endpoint is /api/v2/data-app/embeds. The old endpoint /api/v2/dataApp/embeds will be deprecated soon. Please update your integrations to use the new endpoint format.

This endpoint returns all embeds you have access to within the authenticated data app. The response includes embed IDs, types, and associated dashboard/metric information.

Endpoint Formats

New Endpoint (Recommended)
Legacy Endpoint (Deprecated Soon)

GET https://api.usedatabrain.com/api/v2/data-app/embeds

Use this endpoint for all new integrations. This is the recommended endpoint format.

POST https://api.usedatabrain.com/api/v2/dataApp/embed/list
Content-Type: application/json

{
  "isPagination": true,
  "pageNumber": 1
}

This endpoint still works but will be deprecated. Uses POST method with JSON body.

Authentication

All API requests must include your API key in the Authorization header. Get your API token when creating a data app - see our data app creation guide for details. Finding your API token: For detailed instructions, see the API Token guide.

Headers

Authorization

string

required

Bearer token for API authentication. Use your API key from the data app.

Authorization: Bearer dbn_live_abc123...

Query Parameters

isPagination

string

Whether to paginate results. Pass "true" to enable pagination with a limit of 10 per page.Note: Query parameters are passed as strings. Use "true" or "false".

pageNumber

string

Page number to retrieve (1-based). Only used when isPagination is "true". Must be a numeric string (e.g., "1", "2").

clientId

string

Optional client ID to filter embeds. When provided, only returns dashboard embeds where the dashboard was created by the specified client.

Response

data

array

Array of embed objects with their configuration details.

data.embedId

string

Unique identifier for the embed configuration.

data.embedType

string

Type of embed: “dashboard” or “metric”.

data.name

string

The human-readable name of the embed configuration. This is the name set when creating or renaming the embed configuration.

data.externalDashboard

object | null

Dashboard information (present when embedType is “dashboard”, null otherwise).

data.externalDashboard.externalDashboardId

string

Unique identifier for the external dashboard.

data.externalDashboard.metadata

object

Dashboard metadata information.

data.externalDashboard.name

string

Name of the dashboard.

data.externalMetric

object | null

Metric information (present when embedType is “metric”, null otherwise).

data.externalMetric.metricId

string

Unique identifier for the external metric.

data.externalMetric.name

string

Name of the metric.

data.embedMetadata

object

Consolidated metadata object containing key embed information for easy access.

data.embedMetadata.embedId

string

Unique identifier for the embed configuration.

data.embedMetadata.name

string

The human-readable name of the embed configuration.

data.embedMetadata.embedType

string

Type of embed: “dashboard” or “metric”.

data.embedMetadata.dataAppName

string

Name of the data app associated with this embed.

data.embedMetadata.metricId

string | null

Unique identifier for the metric (present when embedType is “metric”, null otherwise).

data.embedMetadata.dashboardId

string | null

Unique identifier for the dashboard (present when embedType is “dashboard”, null otherwise).

data.embedMetadata.createdAt

string

ISO 8601 formatted timestamp indicating when the embed configuration was created.

data.embedMetadata.updatedAt

string

ISO 8601 formatted timestamp indicating when the embed configuration was last updated.

error

null

Error field, null when successful. Not included in successful responses.

Examples

Error Codes

Error Code	HTTP Status	Description
`INVALID_DATA_APP_API_KEY`	400	Missing or invalid data app
`INTERNAL_SERVER_ERROR`	500	Server error occurred

Quick Start Guide

Get your API token

For detailed instructions, see the API Token guide.

List all embed configurations

Get all your embed configurations:

curl --request GET \
  --url 'https://api.usedatabrain.com/api/v2/data-app/embeds' \
  --header 'Authorization: Bearer dbn_live_abc123...'

Note: You can add query parameters for pagination or filtering if needed.

Use pagination for many embeds

If you have many embed configurations, use pagination with query parameters:

curl --request GET \
  --url 'https://api.usedatabrain.com/api/v2/data-app/embeds?isPagination=true&pageNumber=1' \
  --header 'Authorization: Bearer dbn_live_abc123...'

Manage your embeds

Use the embed information to manage your configurations:

const embeds = await listEmbeds();
embeds.data.forEach(embed => {
  console.log(`Embed ID: ${embed.embedId}`);
  console.log(`Embed Name: ${embed.name}`);
  console.log(`Type: ${embed.embedType}`);
  
  // Access timestamps and IDs from embedMetadata
  console.log(`Created: ${embed.embedMetadata.createdAt}`);
  console.log(`Updated: ${embed.embedMetadata.updatedAt}`);
  console.log(`Data App: ${embed.embedMetadata.dataAppName}`);
  
  if (embed.embedType === 'dashboard' && embed.externalDashboard) {
    console.log(`Dashboard ID: ${embed.externalDashboard.externalDashboardId}`);
    console.log(`Dashboard: ${embed.externalDashboard.name}`);
    console.log(`Dashboard ID (from metadata): ${embed.embedMetadata.dashboardId}`);
  } else if (embed.embedType === 'metric' && embed.externalMetric) {
    console.log(`Metric ID: ${embed.externalMetric.metricId}`);
    console.log(`Metric: ${embed.externalMetric.name}`);
    console.log(`Metric ID (from metadata): ${embed.embedMetadata.metricId}`);
  }
});

Next Steps

Embed a Pre-built Dashboard/Metric

Learn how to create new embed configurations

Update an Embed

Modify existing embed access settings

Delete an Embed

Remove embed configurations you no longer need

Query Metrics API

Query data from your embedded metrics

Create an Empty Dashboard Embed

List Schedule Reports by Embed

Authentication

Datasource APIs

Datamart APIs

Workspace APIs

Embeds

Data App APIs

Metric APIs

Self-Hosted APIs

Endpoint Formats

Authentication

Headers

Query Parameters

Response

Examples

Error Codes

Quick Start Guide

Next Steps

Embed a Pre-built Dashboard/Metric

Update an Embed

Delete an Embed

Query Metrics API

Authentication

Datasource APIs

Datamart APIs

Workspace APIs

Embeds

Data App APIs

Metric APIs

Self-Hosted APIs

​Endpoint Formats

​Authentication

​Headers

​Query Parameters

​Response

​Examples

​Error Codes

​Quick Start Guide

​Next Steps

Embed a Pre-built Dashboard/Metric

Update an Embed

Delete an Embed

Query Metrics API

Endpoint Formats

Authentication

Headers

Query Parameters

Response

Examples

Error Codes

Quick Start Guide

Next Steps