Fetch Metrics by Embed and Client

Retrieve metrics available for a specific embed configuration and client, with support for pagination and client-specific filtering.

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

When set to "true", returns only the list of metrics — excluding elements and summaries. Pass "false" or omit this parameter to return all items, including non-metric components.

Note: Query parameters are passed as strings. Use "true" or "false".

userIdentifier · string

Filter metrics by the user identifier who created them. When provided, only returns metrics created by the specified user.

Show User filtering behavior

• When userIdentifier is provided: Returns only metrics where createdByIdentifier matches
• When omitted: Returns all metrics the client has access to
• System-created metrics (no creator) are excluded when filtering by user
• Useful for showing “My Metrics” views in your application

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.

data.isPublished · boolean

Indicates whether the metric is published and visible to end users.

• true: Metric is published and visible
• false: Metric is unpublished (hidden but not deleted)
• System-created metrics (without a creator) are always true

data.createdByUser · string | null

The identifier of the user who created this metric, or null for system-created metrics.

• Non-null value: Indicates a user-created metric with the creator’s identifier
• null: Indicates a system-created or admin-created metric
• Useful for implementing “My Metrics” filtering and ownership displays

error · object

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

Show Error structure

error.code · string

Machine-readable error code for programmatic handling.

error.message · string

Human-readable error message explaining what went wrong.

Examples

HTTP Status Code Summary

Status Code	Description
200	OK - Metrics retrieved successfully
400	Bad Request - Invalid request parameters, missing required fields, invalid API key, or embed ID not found

Possible Errors

Error Code	HTTP Status	Description
INVALID_DATA_APP_API_KEY	400	Invalid or expired API key
EMBED_PARAM_ERROR	400	Embed ID not found for data app
INVALID_REQUEST_BODY	400	Missing or invalid required parameters

Client Access Control

Metric Visibility Rules

1. Shared Metrics: Available to all clients within the embed
2. Client-Created Metrics: Only visible to the client that created them
3. 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');