Fetch Metrics by Embed and Client

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

{
  "data": [
    {
      "data.name": "<string>",
      "data.metricId": "<string>",
      "data.isPublished": true,
      "data.createdByUser": {}
    }
  ],
  "error": {
    "error.code": "<string>",
    "error.message": "<string>"
  }
}

GET

api

data-app

metrics

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

{
  "data": [
    {
      "data.name": "<string>",
      "data.metricId": "<string>",
      "data.isPublished": true,
      "data.createdByUser": {}
    }
  ],
  "error": {
    "error.code": "<string>",
    "error.message": "<string>"
  }
}

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

string

required

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

Authorization: Bearer dbn_live_abc123...

Query Parameters

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

string

required

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

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

string

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

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

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

array

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

string

Display name of the metric.

string

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

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

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

object

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

Show Error structure

string

Machine-readable error code for programmatic handling.

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

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');

Authentication

Datasource APIs

Datamart APIs

Semantic Layer APIs

Workspace APIs

Embeds

Data App APIs

Metric APIs

Self-Hosted APIs

Fetch Metrics by Embed and Client

Authentication

Headers

Query Parameters

Response

Examples

HTTP Status Code Summary

Possible Errors

Client Access Control

Metric Visibility Rules

Understanding Client-Specific Results

​Authentication

​Headers

​Query Parameters

​Response

​Examples

​HTTP Status Code Summary

​Possible Errors

​Client Access Control

​Metric Visibility Rules

​Understanding Client-Specific Results

Authentication

Headers

Query Parameters

Response

Examples

HTTP Status Code Summary

Possible Errors

Client Access Control

Metric Visibility Rules

Understanding Client-Specific Results