Fetch metric data by data app

Execute queries on metrics within your embedded dashboards and retrieve the resulting data.

Query specific metrics from your embedded dashboards to retrieve data programmatically. This endpoint allows you to fetch metric data with optional filtering and is essential for building custom analytics interfaces or exporting data from your embedded dashboards.

Endpoint Migration Notice: We’re transitioning to kebab-case endpoints. The new endpoint is /api/v2/data-app/query. The old endpoint /api/v2/dataApp/query will be deprecated soon. Please update your integrations to use the new endpoint format.

This endpoint requires an embed ID, metric ID, and client ID. The metric must be associated with the specified embed configuration for the query to succeed.

Endpoint Formats

New Endpoint (Recommended)

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

Use this endpoint for all new integrations. This is the recommended endpoint format.

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

Must be set to application/json for all requests.

Content-Type: application/json

Request Body

embedId · string · required

The unique identifier of the embed configuration containing the metric.

Show Finding embed IDs

• Use the List All Embeds API to get embed IDs
• Check the response from embed creation
• Available in the DataBrain dashboard when viewing embed configurations

metricId · string · required

The unique identifier of the metric to query.

Show Finding metric IDs

• Available in the metric URL: /metric/{metricId}
• Retrieved via the Fetch Metrics by Embed API
• Found in the DataBrain dashboard when viewing a metric

clientId · string · required

Unique identifier for the end user making the query. Used for row-level security and access control.

Show Client ID usage

• Should match the clientId used in guest token generation
• Used for applying row-level security filters
• Consistent across user sessions
• Enables multi-tenant data isolation

dashboardFilter · object

Dashboard-level filters to apply to the metric query. These filters affect the entire dashboard context.

Show Dashboard filter examples

{
  "date_range": {
    "start": "2024-01-01",
    "end": "2024-01-31"
  },
  "region": "north-america",
  "product_category": "electronics"
}

metricFilter · object

Metric-specific filters to apply to the query. Used for row-level security and additional filtering.

Show Metric filter examples

{
  "customer_segment": "enterprise",
  "product_category": "software",
  "status": "active"
}

datasourceName · string

Optional datasource name for multi-datasource environments.

Show Multi-datasource usage

• Required only if your workspace has multiple datasources
• Must match the datasource name configured in your workspace
• Used to route the query to the correct data source

Response

data · array

Array of objects containing the query results. Each object represents a row of data with column names as keys.

Example

[
  {
    "date": "2024-01-01",
    "revenue": 15000,
    "region": "north-america"
  },
  {
    "date": "2024-01-02",
    "revenue": 18000,
    "region": "north-america"
  }
]

timeTaken · number

Query execution time in milliseconds.

comparisonValue · number

Comparison value for metrics with comparison enabled.

totalRecords · number

Total number of records in the result set.

metaData · object

Metadata about the query results.

metaData.columns · array

Array of column information.

metaData.columns.name · string

Column name.

metaData.columns.dataType · string

Data type of the column (e.g., “string”, “number”, “date”).

metaData.groupbyColumnList · array

List of columns used in GROUP BY operations.

metricid · string

The metric ID that was queried (echo of request parameter).

error · null | object

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

Examples

Error Codes

INVALID_EMBED_ID · string

Invalid embed ID - The specified embed ID doesn’t exist or you don’t have access

INVALID_METRIC_ID · string

Invalid metric ID - The specified metric ID doesn’t exist or isn’t associated with the embed

INVALID_DATA_APP_API_KEY · string

Missing or invalid data app - Check your API key and data app configuration

EMBED_PARAM_ERROR · string

Embed ID error - The embed ID was not found or doesn’t match the API key being used

METRIC_NOT_FOUND · string

Metric not found - The specified metric ID doesn’t exist or isn’t associated with the embed configuration

DATASOURCE_NAME_ERROR · string

Invalid datasource name - The specified datasource name doesn’t exist in your workspace

HTTP Status Code Summary

Status Code	Description
200	OK - Query executed successfully
400	Bad Request - Invalid request parameters or missing required fields
401	Unauthorized - Invalid or expired API token
404	Not Found - Embed ID or metric ID not found
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Unexpected server error

Possible Errors

Error Code	HTTP Status	Description
INVALID_EMBED_ID	400	Embed ID not found
INVALID_METRIC_ID	400	Invalid metric ID
INVALID_DATA_APP_API_KEY	401	Missing or invalid data app
EMBED_PARAM_ERROR	404	Embed ID error
METRIC_NOT_FOUND	404	Metric not found
DATASOURCE_NAME_ERROR	400	Invalid datasource name
RATE_LIMIT_EXCEEDED	429	Too many requests
INTERNAL_SERVER_ERROR	500	Unexpected failure

Filtering Guide

Dashboard Filters

Dashboard filters apply to the entire dashboard context and affect all metrics. Common use cases include:

• Date range filtering: Limit data to specific time periods
• Category filtering: Filter by region, department, product line, etc.
• Global parameters: Set values that affect multiple metrics

Example

{
  "dashboardFilter": {
    "date_range": {
      "start": "2024-01-01",
      "end": "2024-03-31"
    },
    "region": "north-america",
    "product_category": "electronics"
  }
}

Metric Filters

Metric filters apply specifically to the metric being queried and can be used for:

• Row-level security (RLS): Restrict data based on client permissions
• Additional filtering: Apply metric-specific conditions
• Client isolation: Ensure multi-tenant data separation

Example

{
  "metricFilter": {
    "department": "sales",
    "status": "active",
    "client_group": "enterprise"
  }
}

Use Cases

Export Dashboard Data

async function exportDashboardData(embedId, clientId) {
  // Get all metrics
  const metricsResponse = await fetch(
    `https://api.usedatabrain.com/api/v2/data-app/metrics?embedId=${embedId}&clientId=${clientId}`,
    {
      headers: { 'Authorization': 'Bearer dbn_live_...' }
    }
  );
  const { data: metrics } = await metricsResponse.json();
  
  // Query each metric
  const allData = {};
  for (const metric of metrics) {
    const queryResponse = await fetch(
      'https://api.usedatabrain.com/api/v2/data-app/query',
      {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer dbn_live_...',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          embedId,
          metricId: metric.metricId,
          clientId
        })
      }
    );
    const queryResult = await queryResponse.json();
    allData[metric.name] = queryResult.data;
  }
  
  return allData;
}

Real-time Data Refresh

async function refreshMetricData(embedId, metricId, clientId, filters) {
  const response = await fetch(
    'https://api.usedatabrain.com/api/v2/data-app/query',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer dbn_live_...',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        embedId,
        metricId,
        clientId,
        dashboardFilter: filters
      })
    }
  );
  
  return await response.json();
}

// Refresh every 5 minutes
setInterval(async () => {
  const data = await refreshMetricData(
    'embed_123',
    'metric_456',
    'user_789',
    { date_range: { start: 'today', end: 'today' } }
  );
  updateDashboard(data);
}, 5 * 60 * 1000);

Multi-Tenant Data Access

async function getClientMetricData(embedId, metricId, clientId) {
  // Apply client-specific filters automatically
  const response = await fetch(
    'https://api.usedatabrain.com/api/v2/data-app/query',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer dbn_live_...',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        embedId,
        metricId,
        clientId,
        metricFilter: {
          // RLS ensures clients only see their data
          client_id: clientId
        }
      })
    }
  );
  
  return await response.json();
}

Best Practices

1. Cache responses - Cache query results when appropriate to reduce API calls and improve performance
2. Use filters efficiently - Apply filters at the query level rather than filtering data client-side
3. Handle pagination - For large datasets, implement pagination or limit results
4. Error handling - Implement robust error handling and retry logic
5. Rate limiting - Respect rate limits and implement exponential backoff
6. Security - Never expose API keys in client-side code; proxy requests through your backend

Performance Tips

• Minimize filter complexity - Complex filters can slow down queries
• Request only needed columns - If possible, select only required columns
• Use date ranges - Limit queries to specific time periods
• Cache when possible - Cache frequently accessed data
• Batch requests - When querying multiple metrics, consider batching requests

Quick Start Guide

1. Get embed and metric IDs

   First, get your embed ID and metric ID from your DataBrain dashboard or via the List APIs:

   # List your embeds to find the embedId
   curl --request GET \
     --url https://api.usedatabrain.com/api/v2/data-app/embeds \
     --header 'Authorization: Bearer dbn_live_abc123...'
   

2. Fetch available metrics

   Use the Fetch Metrics by Embed endpoint to get a list of available metrics:

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

3. Make your first query

   Query a metric with minimal parameters:

   curl --request POST \
     --url https://api.usedatabrain.com/api/v2/data-app/query \
     --header 'Authorization: Bearer dbn_live_abc123...' \
     --header 'Content-Type: application/json' \
     --data '{
       "embedId": "embed_123",
       "metricId": "metric_456", 
       "clientId": "user_789"
     }'
   

4. Add filters for specific data

   Include filters to narrow down your results:

   curl --request POST \
     --url https://api.usedatabrain.com/api/v2/data-app/query \
     --header 'Authorization: Bearer dbn_live_abc123...' \
     --header 'Content-Type: application/json' \
     --data '{
       "embedId": "embed_123",
       "metricId": "metric_456",
       "clientId": "user_789",
       "dashboardFilter": {
         "date_range": {
           "start": "2024-01-01",
           "end": "2024-01-31"
         }
       }
     }'
   

5. Process the results

   Use the returned data in your application:

   const queryData = await queryMetric({
     embedId: 'embed_123',
     metricId: 'metric_456',
     clientId: 'user_789'
   });
   
   console.log(`Found ${queryData.totalRecords} records`);
   console.log(`Query took ${queryData.timeTaken}ms`);
   queryData.data.forEach(row => {
     // Process each data row
     console.log(row);
   });
   

Next Steps

Fetch Metrics by Embed

Get a list of available metrics before querying

Fetch Dashboards by Data App

Retrieve available dashboards in your data app

Create Embed Configuration

Set up embed configurations for your data app

Guest Token API

Generate secure tokens for embedded access