This guide provides everything you need to retrieve data from the Reports API - including authentication steps, endpoint structure, required headers, and query parameters such as date ranges, dimensions, and metrics.
The API supports two response formats for retrieving data:
- Inline JSON response - for quick access to up to 30,000 rows.
- File-based export - for retrieving the full dataset with no row limit, delivered via email as a downloadable file.
Authentication
Retrieving Your API Key
- API keys are generated per user and must be retrieved from the Reports System in Voltax.
- Navigate to the ‘Reports’ and generate an API key under your user profile:
Note: To see this button, make sure the user has the role "API Owner" in Voltax
- Ensure that the user associated with the API key has access to the System reports (data sources) you want to query.
- Note: If you have an API key generated in the Query Builder (“Explore”) in Voltax, it will apply as well.
- If access is restricted, contact your administrator to grant permissions. To access the API, you need an API key. Include it in the request headers as follows:
Authorization: MM-API-Key YOUR_API_KEY
Security Notice: Due to security concerns, API keys expire after 6 months. Users can extend their API key validity 2 weeks before expiration by logging into the Voltax → Reports system and clicking on Extend API where the key was originally generated.
Endpoints
Base URL
Post: https://us-central1-bqservingevents.cloudfunctions.net/mm-reports-prod/api/
Available Endpoint
- Fetch Report Data:
organization/:organization/datasources/:datasourceid/report-query
Please reach out to your AM if you’re not sure what your organization name is.
Request Parameters
Headers
Ensure your request includes the following headers:
Tenant: mmplus
Authorization: MM-API-Key YOUR_API_KEY
Content-Type: application/json
Body Parameters
| Parameter | Type | Description |
| dateRange | array | Custom date range in ["YYYY-MM-DD", "YYYY-MM-DD"] format (e.g., ["2025-03-05", "2025-03-07"]). Use null if using dateRangePreset. |
| dateRangePreset | string | Predefined date range (e.g., 'today', 'yesterday', '7d', '30d', 'month', 'year'). |
| dimensions | array | List of dimensions (e.g., article_title, article_author). |
| filters | array | Filters to apply (leave empty if not needed). |
| limit | integer | Number of records to return (default: 1000). |
| metrics | array | List of metrics to retrieve (e.g., page_views). |
| timezone | string | Timezone for data retrieval (e.g., UTC+0). |
| offset | integer | Number of records to skip (for pagination). |
Fetching All Available Data (No Row Limit)
To retrieve all available data without applying a row limit in the API response, you can request the data as a downloadable file instead of an inline JSON response.
Additional Fields Required in Request Body:
Add the following two fields to your request body:
| Parameter | Type | Description |
| outputType | string | Required. Set to "file" to trigger file-based export instead of inline JSON. |
| string | Required when using outputType = "file". The download link will be sent to this email address. |
Requests Examples
Inline JSON response (30k rows limit):
curl --location 'https://us-central1-bqservingevents.cloudfunctions.net/mm-reports-prod/api/organization/:organization/datasources/:datasourceid/report-query' \
--header 'Tenant: mmplus' \
--header 'Authorization: MM-API-Key YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"dateRange": ["2025-03-01", "2025-03-04"],
"dimensions": ["domain"],
"filters": [],
"limit": 1000,
"metrics": ["sessionsBySessionId", "pagesPerSession", "revenue", "TotalRPS", "DisplayRPS", "VideoRPS"],
"timezone": "UTC+0",
"offset": 0
}'
Response:
"{
"version": "1.2.12",
"data": {
"reports": [
{
"domain": "******.com",
"sessionsBySessionId": ***,
"pagesPerSession": ******,
"pageViews": ****8,
"sessions": ****,
"revenue": ,
"TotalRPS": ,
"DisplayRPS": ,
"revenueDisplay": ,
"VideoRPS": ,
"revenueVideo":
}],
"count": ***
}
}
Note: In the response, you will see the field "count", which indicates the overall number of results that match your query.
Downloadable file response (no limit):
curl --location 'https://us-central1-bqservingevents.cloudfunctions.net/mm-reports-prod/api/organization/:organization/datasources/:datasourceid/report-query' \
--header 'Tenant: mmplus' \
--header 'Authorization: MM-API-Key YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"dateRange": ["2025-03-01", "2025-03-04"],
"dimensions": ["domain"],
"filters": [],
"metrics": ["sessionsBySessionId", "pagesPerSession", "revenue", "TotalRPS", "DisplayRPS", "VideoRPS"],
"timezone": "UTC+0",
"outupType": "file",
"email": "*****@minutemedia.com"
}'
Response:
{
"version": "1.2.12",
"data": {
"jobId": "7f427647-aa25-40a1-a854-70390cff60e2"
}
}
What Happens Next:
- The response will include a jobId that represents the export request.
- The system will generate a CSV file containing all data matching your query, without a row limit.
- A secure download link will be sent to the email provided in the request.
- The link will remain valid for a limited time (24H).
Note: If outputType is not provided, the API defaults to returning a JSON response inline, with up to 30,000 rows. Use offset for paginated results in that case.
Email Image:
For any issues, please contact helpdesk@minutemedia.com.