Data Retrieval
Query a metric
Get the rows of an embedded metric for one customer, from your backend.
Databrain runs the metric of a metric embed for the tenant in clientId and returns the rows. No guest token is used.
curl --request POST https://api.usedatabrain.com/api/v2/data-app/query \ --header "Authorization: Bearer $DATABRAIN_API_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "dataAppId": "7c8d9e0f-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "embedId": "monthly-revenue", "metricId": "b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e", "clientId": "acme" }'Auth
A data app API token, or a service token. With a service token, dataAppId picks the data app. With a data app API token, its own data app is used. See Authentication.
ApiTokenAuthorizationBearer <token>A service token or a data app API token.
Body
Unknown fields are refused, timezone too.
The data app id (dataAppId in List embeds). With a data app API token it must be that token's data app.
The embed id of a metric embed.
The metric id. The embed decides which metric runs; this value is not used to pick it.
The tenant whose rows you get.
Dashboard filter values: { "tableName": "...", "filters": [ ... ] }
Row conditions on the metric.
Multi-datasource workspaces: the datasource to query.
Multi-datamart workspaces: the datamart to query.
Response
{ "data": [ { "month": "2026-10", "revenue": 182340.5 }, { "month": "2026-11", "revenue": 194112.0 } ], "timeTaken": 412, "metaData": { "groupbyColumnList": ["month"] }}| Field | Description |
|---|---|
data | The rows. Up to the metric's own row limit, or 10,000 |
timeTaken | Query time in milliseconds |
metaData.groupbyColumnList | The group-by columns |
metaData.rowsTruncated, metaData.rowLimit | Set when rows were cut at the limit |
comparisonValue | { "mainValue", "compareValue" } for a single-value metric with a comparison |
totalRecords | Total row count, when the metric has one |
When the warehouse query fails, you still get 200 with data: []. An empty data can mean no rows or a failed query. Check the metric in the app if you expect rows.
Errors
| Status | error.code | Why |
|---|---|---|
| 400 | INVALID_REQUEST_BODY | A field is missing or unknown |
| 400 | INVALID_EMBED_ID | No embed of this data app has this id |
| 400 | INVALID_METRIC_ID | The embed is a dashboard embed, not a metric embed |
| 400 | DATASOURCE_NAME_ERROR or DATAMART_NAME_ERROR | The datasource or datamart name is unknown |
| 403 | DATA_APP_ID_ERROR | dataAppId is not the data app of your API token |
| 404 | DATA_APP_NOT_FOUND | No data app in your organization has this id |
| 500 | INTERNAL_SERVER_ERROR | The request failed, for example dataAppId is not a UUID |
For errors that every endpoint returns, see Authentication.
curl -X POST 'https://api.usedatabrain.com/api/v2/data-app/query' \ -H 'Content-Type: application/json' \ -d '{ "dataAppId": "7c8d9e0f-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "embedId": "monthly-revenue", "metricId": "b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e", "clientId": "acme"}'{ "data": [ { "month": "2026-10", "revenue": 182340.5 }, { "month": "2026-11", "revenue": 194112 } ], "timeTaken": 412, "comparisonValue": null, "totalRecords": 2, "metaData": { "groupbyColumnList": [ "month" ] }}