Skip to Content

Data Retrieval

Query a metric

Get the rows of an embedded metric for one customer, from your backend.

POST
/api/v2/data-app/query

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.

Authorization

ApiToken
headerAuthorizationBearer <token>

A service token or a data app API token.

Body

Unknown fields are refused, timezone too.

dataAppIdstringrequired

The data app id (dataAppId in List embeds). With a data app API token it must be that token's data app.

embedIdstringrequired

The embed id of a metric embed.

metricIdstringrequired

The metric id. The embed decides which metric runs; this value is not used to pick it.

clientIdstringrequired

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"] }}
FieldDescription
dataThe rows. Up to the metric's own row limit, or 10,000
timeTakenQuery time in milliseconds
metaData.groupbyColumnListThe group-by columns
metaData.rowsTruncated, metaData.rowLimitSet when rows were cut at the limit
comparisonValue{ "mainValue", "compareValue" } for a single-value metric with a comparison
totalRecordsTotal 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

Statuserror.codeWhy
400INVALID_REQUEST_BODYA field is missing or unknown
400INVALID_EMBED_IDNo embed of this data app has this id
400INVALID_METRIC_IDThe embed is a dashboard embed, not a metric embed
400DATASOURCE_NAME_ERROR or DATAMART_NAME_ERRORThe datasource or datamart name is unknown
403DATA_APP_ID_ERRORdataAppId is not the data app of your API token
404DATA_APP_NOT_FOUNDNo data app in your organization has this id
500INTERNAL_SERVER_ERRORThe request failed, for example dataAppId is not a UUID

For errors that every endpoint returns, see Authentication.

Example Request
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"}'
Example Response
{  "data": [    {      "month": "2026-10",      "revenue": 182340.5    },    {      "month": "2026-11",      "revenue": 194112    }  ],  "timeTaken": 412,  "comparisonValue": null,  "totalRecords": 2,  "metaData": {    "groupbyColumnList": [      "month"    ]  }}