Skip to main content
POST
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

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.
string
required
Must be set to application/json for all requests.

Request Body

string
required
The unique identifier of the embed configuration containing the metric.
string
required
The unique identifier of the metric to query.
string
required
Unique identifier for the end user making the query. Used for row-level security and access control.
object
Dashboard-level filters to apply to the metric query. These filters affect the entire dashboard context.
object
Metric-specific filters to apply to the query. Used for row-level security and additional filtering.
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).
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).

Response

array
Array of objects containing the query results. Each object represents a row of data with column names as keys.
Example
number
Query execution time in milliseconds.
number
Comparison value for metrics with comparison enabled.
number
Total number of records in the result set.
object
Metadata about the query results.
array
Array of column information.
string
Column name.
string
Data type of the column (e.g., “string”, “number”, “date”).
array
List of columns used in GROUP BY operations.
string
The metric ID that was queried (echo of request parameter).
null | object
Error object if the request failed, otherwise null for successful requests.

Examples

Error Codes

string
Invalid embed ID - The specified embed ID doesn’t exist or you don’t have access
string
Invalid metric ID - The specified metric ID doesn’t exist or isn’t associated with the embed
string
Missing or invalid data app - Check your API key and data app configuration
string
Embed ID error - The embed ID was not found or doesn’t match the API key being used
string
Metric not found - The specified metric ID doesn’t exist or isn’t associated with the embed configuration
string
Invalid datasource name - The specified datasource name could not be resolved for a multi-datasource workspace
string
Invalid datamart name - The specified dataMartName could not be resolved for a multi-datamart workspace

HTTP Status Code Summary

Possible Errors

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

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

Use Cases

Export Dashboard Data

Real-time Data Refresh

Multi-Tenant Data Access

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:
2

Fetch available metrics

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

Make your first query

Query a metric with minimal parameters:
4

Add filters for specific data

Include filters to narrow down your results:
5

Process the results

Use the returned data in your application:

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