Fetch Dashboards by Data App

Fetch all dashboards associated with your data app. This endpoint allows you to discover available dashboards for embedding or integration purposes, with support for filtering by dashboard names and pagination.

API Method Migration Notice: We’re transitioning from POST to GET for this endpoint. The new GET method is recommended for all new integrations. The POST method will be deprecated soon.

This endpoint returns dashboards that have been configured for your data app. Use the dashboard information to create embed configurations or for display purposes.

API Methods

GET (Recommended)
POST (Deprecated Soon)

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

Use this method for all new integrations. This is the recommended approach with query parameters.

POST https://api.usedatabrain.com/api/v2/data-app/dashboards

This method still works but will be deprecated. Please migrate to the GET method.

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

Content-Type

string

Required only for POST method. Must be set to application/json.

Content-Type: application/json

Query Parameters

isPagination

string

required

Enable pagination to limit the number of results returned. 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

required

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

dashboardNames

string

Comma-separated list of dashboard names to filter by. Only dashboards with matching names will be returned.Example: "Sales Dashboard,Marketing Analytics,Customer Insights"

Examples

Legacy Endpoint Examples

The following examples use the deprecated POST method. These are provided for reference only. Please use the GET method examples above for all new integrations.

POST Method (Legacy - Being Deprecated)

Request Body (POST)

isPagination

boolean

Enable pagination to limit the number of results returned. When enabled, use pageNumber to navigate through pages.

pageNumber

number

Page number for pagination (1-based). Only used when isPagination is true. Each page returns up to 10 dashboards.

filters

object

Optional filters to narrow down the dashboard results.

filters.dashboardNames

array

Array of specific dashboard names to filter by. Only dashboards with matching names will be returned.

Example

["Sales Dashboard", "Marketing Analytics", "Customer Insights"]

POST Examples

Response (Success 200)

data

array

Array of dashboard objects available in your data app.

data.name

string

Display name of the dashboard.

data.externalDashboardId

string

Unique identifier for the dashboard that can be used in embed configurations.

data.embedId

string

Embed ID associated with this dashboard, if available.

Error Response

error

object

Error object returned only when the request fails. Not included in successful responses.

error.code

string

Error code identifier.

error.message

string

Human-readable error message.

Error Codes

INVALID_DATA_APP_API_KEY

string

Invalid or missing Data App API Key - Check your API key and ensure it’s valid for your data app

INVALID_REQUEST_BODY

string

Invalid request parameters - Verify that your request body contains valid field types

HTTP Status Code Summary

Status Code	Description
`200`	OK - Dashboards retrieved successfully
`400`	Bad Request - Invalid request parameters or missing API key
`401`	Unauthorized - Invalid or missing API key
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Server error occurred

Possible Errors

Error Code	HTTP Status	Description
`INVALID_DATA_APP_API_KEY`	401	Invalid API key
`INVALID_REQUEST_BODY`	400	Invalid request body
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`INTERNAL_SERVER_ERROR`	500	Server error

Pagination Guide

When using pagination:

Enable pagination by setting isPagination to true (GET) or true (POST)
Start with page 1 using pageNumber=1 (GET) or pageNumber: 1 (POST)
Each page returns up to 10 dashboards
Continue to next page if you receive exactly 10 results
Stop pagination when you receive fewer than 10 results

GET Method Pagination Example:

GET /api/v2/data-app/dashboards?isPagination=true&pageNumber=1

POST Method Pagination Example:

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

Filtering Options

Dashboard Name Filtering

GET Method: Use comma-separated values in query parameter

?dashboardNames=Dashboard%201,Dashboard%202

POST Method: Use array in request body

{
  "filters": {
    "dashboardNames": ["Dashboard 1", "Dashboard 2"]
  }
}

This is useful when you know the exact dashboard names you want to work with.

Migration Guide: POST to GET

If you’re currently using the POST method, here’s how to migrate to GET:

Before (POST):

const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/dashboards', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer dbn_live_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    isPagination: true,
    pageNumber: 1,
    filters: {
      dashboardNames: ['Sales Dashboard']
    }
  })
});

After (GET):

const params = new URLSearchParams({
  isPagination: 'true',
  pageNumber: '1',
  dashboardNames: 'Sales Dashboard'
});

const response = await fetch(`https://api.usedatabrain.com/api/v2/data-app/dashboards?${params}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer dbn_live_...'
  }
});

Key Differences:

Method: POST → GET
Parameters: Request body → Query parameters
Boolean values: true → "true" (string in query params)
Number values: 1 → "1" (string in query params)
Dashboard names: Array ["name1", "name2"] → Comma-separated string "name1,name2"
Content-Type header: Not needed for GET

Quick Start Guide

Get your API token

For detailed instructions, see the API Token guide.

List all dashboards (GET - Recommended)

Get all dashboards available in your data app:

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

Filter by specific dashboard names

If you’re looking for specific dashboards, use query parameters:

curl --request GET \
  --url 'https://api.usedatabrain.com/api/v2/data-app/dashboards?dashboardNames=Sales%20Dashboard,Marketing%20Analytics' \
  --header 'Authorization: Bearer dbn_live_abc123...'

Use dashboard information for embedding

Process the dashboard data to create embed configurations:

const dashboards = await fetchDataAppDashboards();

dashboards.data.forEach(dashboard => {
  console.log(`Dashboard: ${dashboard.name}`);
  console.log(`External ID: ${dashboard.externalDashboardId}`);
  
  // Use the externalDashboardId to create embed configurations
  if (!dashboard.embedId) {
    console.log('This dashboard can be made embeddable');
  }
});

Next Steps

Embed a Pre-built Dashboard/Metric

Use dashboard IDs to create embed configurations

Fetch Metrics by Embed

Get metrics available for specific embedded dashboards

Query Metric Data

Query data from your dashboard metrics

Guest Token API

Generate secure tokens for embedded access

Authentication

Datasource APIs

Datamart APIs

Workspace APIs

Embeds

Data App APIs

Metric APIs

Self-Hosted APIs

Fetch Dashboards by Data App

API Methods

Authentication

Headers

Query Parameters

Examples

Legacy Endpoint Examples

POST Method (Legacy - Being Deprecated)

Request Body (POST)

POST Examples

Response (Success 200)

Error Response

Error Codes

HTTP Status Code Summary

Possible Errors

Filtering Options

Dashboard Name Filtering

Migration Guide: POST to GET

Before (POST):

After (GET):

Key Differences:

Quick Start Guide

Next Steps

Embed a Pre-built Dashboard/Metric

Fetch Metrics by Embed

Query Metric Data

Guest Token API

Authentication

Datasource APIs

Datamart APIs

Workspace APIs

Embeds

Data App APIs

Metric APIs

Self-Hosted APIs

​API Methods

​Authentication

​Headers

​Query Parameters

​Examples

​Legacy Endpoint Examples

​POST Method (Legacy - Being Deprecated)

​Request Body (POST)

​POST Examples

​Response (Success 200)

​Error Response

​Error Codes

​HTTP Status Code Summary

​Possible Errors

​Pagination Guide

​GET Method Pagination Example:

​POST Method Pagination Example:

​Filtering Options

​Dashboard Name Filtering

​Migration Guide: POST to GET

​Before (POST):

​After (GET):

​Key Differences:

​Quick Start Guide

​Next Steps

Embed a Pre-built Dashboard/Metric

Fetch Metrics by Embed

Query Metric Data

Guest Token API

API Methods

Authentication

Headers

Query Parameters

Examples

Legacy Endpoint Examples

POST Method (Legacy - Being Deprecated)

Request Body (POST)

POST Examples

Response (Success 200)

Error Response

Error Codes

HTTP Status Code Summary

Possible Errors

Pagination Guide

GET Method Pagination Example:

POST Method Pagination Example:

Filtering Options

Dashboard Name Filtering

Migration Guide: POST to GET

Before (POST):

After (GET):

Key Differences:

Quick Start Guide

Next Steps