Fetch Metrics by Embed and Client

Get a list of metrics that are accessible through a specific embed configuration for a particular client. This endpoint is essential for understanding what metrics are available for querying within an embedded dashboard context.

This endpoint returns metrics filtered by client access. Client-created metrics are only visible to the specific client that created them, while shared metrics are visible to all clients.

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

embedId

string

required

The embed configuration ID to fetch metrics for. This identifies which embedded dashboard’s metrics you want to retrieve.

Show Finding embed IDs

Created when you configure an embed via the Create Embed API
Retrieved via the List Embeds API
Available in your DataBrain dashboard embed settings

clientId

string

required

The client identifier for filtering metrics. Determines which metrics the client has access to based on their permissions and ownership.

isPagination

string

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

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

isMetric

string

Filter to return only metrics when set to "true". Pass "false" or omit to return all items including non-metric components.Note: Query parameters are passed as strings. Use "true" or "false".

Response

data

array

Array of metric objects available for the specified embed and client.

data.name

string

Display name of the metric.

data.metricId

string

Unique identifier for the metric that can be used in query operations.

error

null | object

Error object if the request failed, otherwise null for successful requests.

Examples

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 required fields embedId and clientId are provided with correct types

EMBED_PARAM_ERROR

string

Embed ID not found or mismatched with API Key - The embed ID doesn’t exist or doesn’t belong to your data app

HTTP Status Code Summary

Status Code	Description
`200`	OK - Metrics retrieved successfully
`400`	Bad Request - Invalid request parameters or missing required fields
`401`	Unauthorized - Invalid or missing API key
`404`	Not Found - Embed ID not found
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Server error occurred

Possible Errors

Error Code	HTTP Status	Description	Solution
`INVALID_DATA_APP_API_KEY`	401	Invalid API key	Check your API key and permissions
`EMBED_PARAM_ERROR`	404	Embed ID not found	Verify embed ID exists and belongs to your data app
`INVALID_REQUEST_BODY`	400	Missing required fields	Provide both embedId and clientId
`RATE_LIMIT_EXCEEDED`	429	Too many requests	Implement exponential backoff
`INTERNAL_SERVER_ERROR`	500	Server error	Contact support if error persists

Client Access Control

Metric Visibility Rules

Shared Metrics: Available to all clients within the embed
Client-Created Metrics: Only visible to the client that created them
Access Settings: Controlled by the embed configuration’s access settings

Understanding Client-Specific Results

The API automatically filters metrics based on the client’s access permissions:

// Client A will see their own metrics + shared metrics
const clientAMetrics = await fetchMetrics('embed_123', 'client_A');

// Client B will see their own metrics + shared metrics (different from Client A)
const clientBMetrics = await fetchMetrics('embed_123', 'client_B');

Pagination Guide

When working with large metric collections:

Enable pagination by setting query parameter isPagination=true
Start with page 1 using pageNumber=1
Filter only metrics by setting isMetric=true (optional)
Each page returns up to 10 metrics
Continue to next page if you receive exactly 10 results
Stop pagination when you receive fewer than 10 results

Example with pagination:

GET /api/v2/data-app/metrics?embedId=embed_123&clientId=client_xyz&isPagination=true&pageNumber=1&isMetric=true

Integration Workflow

Step 1: Get Available Metrics

const params = new URLSearchParams({
  embedId: 'your_embed_id',
  clientId: 'your_client_id'
});

const metricsResponse = await fetch(`/api/v2/dataApp/metrics?${params}`, {
  method: 'GET',
  headers: { 'Authorization': 'Bearer dbn_live_...' }
});

Step 2: Use Metrics for Queries

const metrics = metricsResponse.data;
for (const metric of metrics) {
  // Use metric.metricId in query operations
  const queryResult = await queryMetric({
    metricId: metric.metricId,
    embedId: 'your_embed_id',
    clientId: 'your_client_id'
  });
}

Quick Start Guide

Get your embed ID

First, you need an embed ID. Get it from your embed configurations:

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

Fetch metrics for a client

Get the metrics available for a specific client and embed:

curl --request GET \
  --url 'https://api.usedatabrain.com/api/v2/data-app/metrics?embedId=embed_abc123&clientId=client_xyz789' \
  --header 'Authorization: Bearer dbn_live_abc123...'

Use pagination for many metrics

If there are many metrics, use pagination with query parameters. Add isMetric=true to filter only metrics:

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

Use metric IDs for queries

Use the returned metric IDs to query actual data:

const metrics = await fetchMetricsByEmbed({
  embedId: 'embed_abc123',
  clientId: 'client_xyz789'
});

// Use the metric IDs for data queries
metrics.data.forEach(metric => {
  console.log(`Metric: ${metric.name} (ID: ${metric.metricId})`);
  // Now query this metric using the Query Metrics API
});

Next Steps

Query Metrics API

Use metric IDs to query actual data from your metrics

Create Embed Configuration

Configure embed settings to control metric access

Fetch Dashboards by Data App

Get available dashboards for your embed configurations

Guest Token API

Generate secure tokens for embedded metric access

Authentication

Datamart APIs

Embed Configuration

Embedding APIs (Legacy)

Data App APIs

Fetch Metrics by Embed and Client

Authentication

Headers

Query Parameters

Response

Examples

Error Codes

HTTP Status Code Summary

Possible Errors

Client Access Control

Metric Visibility Rules

Understanding Client-Specific Results

Integration Workflow

Step 1: Get Available Metrics

Step 2: Use Metrics for Queries

Quick Start Guide

Next Steps

Query Metrics API

Create Embed Configuration

Fetch Dashboards by Data App

Guest Token API

Authentication

Datamart APIs

Embed Configuration

Embedding APIs (Legacy)

Data App APIs

​Authentication

​Headers

​Query Parameters

​Response

​Examples

​Error Codes

​HTTP Status Code Summary

​Possible Errors

​Client Access Control

​Metric Visibility Rules

​Understanding Client-Specific Results

​Pagination Guide

​Integration Workflow

​Step 1: Get Available Metrics

​Step 2: Use Metrics for Queries

​Quick Start Guide

​Next Steps

Query Metrics API

Create Embed Configuration

Fetch Dashboards by Data App

Guest Token API

Authentication

Headers

Query Parameters

Response

Examples

Error Codes

HTTP Status Code Summary

Possible Errors

Client Access Control

Metric Visibility Rules

Understanding Client-Specific Results

Pagination Guide

Integration Workflow

Step 1: Get Available Metrics

Step 2: Use Metrics for Queries

Quick Start Guide

Next Steps