Reporting API Reference
This article covers everything you need to build and run requests against the BA Reporting API: authentication, request structure, filters, and response format.
Endpoint
The endpoint for requesting report data is:
https://engine.brightanalytics.io/reporting-api/run
Request Type
The Reporting API expects a POST request.
Headers
Header | Value | Notes |
|
| Support will assist in generation of API tokens. |
| Your tenant ID (uppercase alphanumeric string) | Uniquely identifies your BA instance. Support will confirm the Tenant ID for your instance(s). |
|
| Required |
Request body
All requests must be a JSON object with the following top-level fields:
Field | Required | Type | Description |
| Yes | array | At least one metric to return. Each item is |
| No | array | Dimensions to break the data down by. Each item is |
| No | array | Filters applied to dimensions (see below). |
| Yes | object |
|
| No | string | Controls the key used to label each field in the returned rows. One of |
What is a "ref"?
When requesting a metric or dimension you must specify one of 2 values as the 'ref'.
ID
This is the numeric ID associated with a given metric or dimension
The BA Ref value
This is a short, meaningful, human-readable code (e.g.cost_per_click) label that is defined per metric or dimensions the Semantic Layer interface.
This is configured in the settings tab of your Metric or Dimension:
When building metrics, dimensions, or filters, the ref field in your request can be either the numeric ID or the BA ref - both are accepted.
Filters
Filters apply only to dimensions. Each filter object requires a ref and a type, plus either values or search depending on the type:
Type | Requires | Behavior |
|
| Include rows where the dimension value matches one of the given values. |
|
| Exclude rows where the dimension value matches one of the given values. |
|
| Include rows where the dimension value contains the given substring. |
|
| Exclude rows where the dimension value contains the given substring. |
|
| Include rows where the dimension value matches the given regular expression. |
|
| Exclude rows where the dimension value matches the given regular expression. |
| neither | Exclude rows where the dimension value is an empty string. |
Date range
Dates are specified as YYYY-MM-DD and represent the calendar dates you want data for, regardless of your local timezone — timezone normalization is handled upstream in our data pipeline, so no timezone conversion is needed on your end.
Response Data Key
The response_data_key field in your request controls which identifier is used as the key for each value inside a row object:
id— keys are numeric metric/dimension IDsref— keys are the BA ref valuesname— keys are the display names
The default behaviour - if response_data_key is not defined - is to return the 'BA ref' for a metric or dimension.
Response
A successful response includes:
rows — the actual data, one object per row
report_specification — an echo of the request you sent
metrics / dimensions — metadata for each metric/dimension used in the request (id, ref, name, formatting info)
row_count, run_duration, generated_at — metadata about the run
Example request
{
"metrics":[
{
"ref":"56"
}
],
"dimensions":[
{
"ref":"1"
},
{
"ref":"33"
}
],
"filters":[
{
"ref":"33",
"type":"in",
"values":[
"Paid Search",
"Paid Social",
"Display"
]
}
],
"date_range":{
"start":"2026-06-15",
"end":"2026-06-15"
}
}
Example response
{
"rows":[
{
"date":"2026-06-15 (Mon)",
"channel":"Display",
"media_cost":46427.07
},
{
"date":"2026-06-15 (Mon)",
"channel":"Paid Search",
"media_cost":18251
},
{
"date":"2026-06-15 (Mon)",
"channel":"Paid Social",
"media_cost":3152.5487000000003
}
],
"report_specification":{
"metrics":[
{
"ref":"56"
}
],
"dimensions":[
{
"ref":"1"
},
{
"ref":"33"
}
],
"filters":[
{
"ref":"33",
"type":"in",
"values":[
"Paid Search",
"Paid Social",
"Display"
]
}
],
"date_range":{
"start":"2026-06-15",
"end":"2026-06-15"
}
},
"metrics":[
{
"id":56,
"ref":"media_cost",
"name":"Media Cost",
"info":"Media Cost : CM360 + DV360 + SA360 + Meta Ads + Twitter Ads ",
"context":null,
"prefix":"£",
"suffix":"",
"decimals":2
}
],
"dimensions":[
{
"id":1,
"ref":"date",
"name":"Date",
"info":"",
"context":null
},
{
"id":33,
"ref":"channel",
"name":"Channel",
"info":"Channel name from all sources ",
"context":null
}
],
"row_count":3,
"run_duration":0.28710198402404785,
"generated_at":"2026-07-15T10:41:38.135107Z"
}
The full response also includes report_specification, and metrics/dimensions metadata arrays at the end o the response. The meta data for metrics and dimensions is for adding additional context - particularly when it comes to metrics - such as rounding, prefix, suffix, as well as additional information and context fields.
Errors
The API validates your request and returns a descriptive error message when something is wrong (e.g. a missing required field, an invalid filter combination, or an unrecognized ref). A typical error response looks like:
{
"message": "The required properties (metrics, date_range) are missing",
"errors": {
"": [
"The required properties (metrics, date_range) are missing"]
}
}
Rate limits & pagination
There are currently no rate limits or pagination on this endpoint.
Pagination support is planned for a future release.
Coming Soon
Features updates we have planned include:
Pagination - for especially large reports we will paginate results
Copy report specification from an existing report. This will make it easy to create a valid report specification to use as an API request start-point.
Metric and Dimension 'list' endpoints.