Fetch metric data by data app

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"
      }
    },
    "metricFilter": {
      "region": "north-america"
    }
  }'

{
  "data": [
    {
      "date": "2024-01-01",
      "revenue": 15000,
      "region": "north-america",
      "customer_count": 45
    },
    {
      "date": "2024-01-02", 
      "revenue": 18500,
      "region": "north-america",
      "customer_count": 52
    },
    {
      "date": "2024-01-03",
      "revenue": 16500,
      "region": "north-america",
      "customer_count": 138
    }
  ],
  "timeTaken": 245,
  "comparisonValue": 12500,
  "totalRecords": 31,
  "metaData": {
    "columns": [
      {
        "name": "date",
        "dataType": "date"
      },
      {
        "name": "revenue",
        "dataType": "number"
      },
      {
        "name": "region",
        "dataType": "string"
      },
      {
        "name": "customer_count",
        "dataType": "number"
      }
    ],
    "groupbyColumnList": ["date", "region"]
  },
  "metricid": "metric_456",
  "error": null
}

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"
      }
    },
    "metricFilter": {
      "region": "north-america"
    }
  }'

{
  "data": [
    {
      "date": "2024-01-01",
      "revenue": 15000,
      "region": "north-america",
      "customer_count": 45
    },
    {
      "date": "2024-01-02", 
      "revenue": 18500,
      "region": "north-america",
      "customer_count": 52
    },
    {
      "date": "2024-01-03",
      "revenue": 16500,
      "region": "north-america",
      "customer_count": 138
    }
  ],
  "timeTaken": 245,
  "comparisonValue": 12500,
  "totalRecords": 31,
  "metaData": {
    "columns": [
      {
        "name": "date",
        "dataType": "date"
      },
      {
        "name": "revenue",
        "dataType": "number"
      },
      {
        "name": "region",
        "dataType": "string"
      },
      {
        "name": "customer_count",
        "dataType": "number"
      }
    ],
    "groupbyColumnList": ["date", "region"]
  },
  "metricid": "metric_456",
  "error": null
}

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"
      }
    },
    "metricFilter": {
      "region": "north-america"
    }
  }'

{
  "data": [
    {
      "date": "2024-01-01",
      "revenue": 15000,
      "region": "north-america",
      "customer_count": 45
    },
    {
      "date": "2024-01-02", 
      "revenue": 18500,
      "region": "north-america",
      "customer_count": 52
    },
    {
      "date": "2024-01-03",
      "revenue": 16500,
      "region": "north-america",
      "customer_count": 138
    }
  ],
  "timeTaken": 245,
  "comparisonValue": 12500,
  "totalRecords": 31,
  "metaData": {
    "columns": [
      {
        "name": "date",
        "dataType": "date"
      },
      {
        "name": "revenue",
        "dataType": "number"
      },
      {
        "name": "region",
        "dataType": "string"
      },
      {
        "name": "customer_count",
        "dataType": "number"
      }
    ],
    "groupbyColumnList": ["date", "region"]
  },
  "metricid": "metric_456",
  "error": null
}

POST

api

data-app

query

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"
      }
    },
    "metricFilter": {
      "region": "north-america"
    }
  }'

{
  "data": [
    {
      "date": "2024-01-01",
      "revenue": 15000,
      "region": "north-america",
      "customer_count": 45
    },
    {
      "date": "2024-01-02", 
      "revenue": 18500,
      "region": "north-america",
      "customer_count": 52
    },
    {
      "date": "2024-01-03",
      "revenue": 16500,
      "region": "north-america",
      "customer_count": 138
    }
  ],
  "timeTaken": 245,
  "comparisonValue": 12500,
  "totalRecords": 31,
  "metaData": {
    "columns": [
      {
        "name": "date",
        "dataType": "date"
      },
      {
        "name": "revenue",
        "dataType": "number"
      },
      {
        "name": "region",
        "dataType": "string"
      },
      {
        "name": "customer_count",
        "dataType": "number"
      }
    ],
    "groupbyColumnList": ["date", "region"]
  },
  "metricid": "metric_456",
  "error": null
}

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)
Legacy Endpoint (Deprecated Soon)

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

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

POST https://api.usedatabrain.com/api/v2/dataApp/query

This endpoint still works but will be deprecated. Please migrate to the new 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 string. Use when the dashboard’s workspace is configured for multiple datasources (MULTI_DATASOURCE): pass the datasource name (as in Data Studio / your integration credentials) so the query runs against that datasource. If the name does not resolve, the API returns DATASOURCE_NAME_ERROR (400).

Show Details

Not used for multi-datamart workspaces; use dataMartName instead when applicable
For workspaces that are not multi-datasource, omit this field unless your integration already relies on it

dataMartName

string

Optional string. Use the exact JSON property name dataMartName (camelCase with a capital M in Mart).When the dashboard’s workspace is configured for multiple datamarts (MULTI_DATAMART), pass the datamart name so the query resolves that datamart’s linked datasource. Names follow the same rules as in the List Datamarts API. If the name does not resolve, the API returns DATAMART_NAME_ERROR (400).

Show Details

Not used for multi-datasource workspaces; use datasourceName instead when applicable
Distinct from workspace create/update body field datamartName (different casing for this endpoint)

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 could not be resolved for a multi-datasource workspace

DATAMART_NAME_ERROR

string

Invalid datamart name - The specified dataMartName could not be resolved for a multi-datamart 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 (multi-datasource)
`DATAMART_NAME_ERROR`	400	Invalid datamart name (multi-datamart)
`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

Cache responses - Cache query results when appropriate to reduce API calls and improve performance
Use filters efficiently - Apply filters at the query level rather than filtering data client-side
Handle pagination - For large datasets, implement pagination or limit results
Error handling - Implement robust error handling and retry logic
Rate limiting - Respect rate limits and implement exponential backoff
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

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

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

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"
  }'

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"
      }
    }
  }'

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

Embed a Pre-built Dashboard/Metric

Set up embed configurations for your data app

Guest Token API

Generate secure tokens for embedded access

Fetch Metrics by Embed and Client

Export Dashboard

Documentation Index

​Endpoint Formats

​Authentication

​Headers

​Request Body

​Response

​Examples

​Error Codes

​HTTP Status Code Summary

​Possible Errors

​Filtering Guide

​Dashboard Filters

​Metric Filters

​Use Cases

​Export Dashboard Data

​Real-time Data Refresh

​Multi-Tenant Data Access

​Best Practices

​Performance Tips

​Quick Start Guide

​Next Steps

Fetch Metrics by Embed

Fetch Dashboards by Data App

Embed a Pre-built Dashboard/Metric

Guest Token API

Endpoint Formats

Authentication

Headers

Request Body

Response

Examples

Error Codes

HTTP Status Code Summary

Possible Errors

Filtering Guide

Dashboard Filters

Metric Filters

Use Cases

Export Dashboard Data

Real-time Data Refresh

Multi-Tenant Data Access

Best Practices

Performance Tips

Quick Start Guide

Next Steps