Skip to main content
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
/
v2
/
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

​
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 CodeHTTP StatusDescription
INVALID_DATA_APP_API_KEY400Missing or invalid data app
INTERNAL_SERVER_ERROR500Server error occurred

​
Quick Start Guide

1

Get your API token

For detailed instructions, see the API Token guide.
2

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.
3

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...'
4

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