Manage reports with the API
Overview
With the Maestro Reporting API, developers can automate a range of reporting tasks, such as creating, updating, or deleting reports, setting up scheduled reports, and more.
The Reporting API is asynchronous, meaning it delivers fully processed data rather than real-time or preliminary results. The data returned is final and won't be recalculated or adjusted by Equativ.
Web API client
Use the Web API client (powered by Scalar) to explore the API and view inline documentation for all operations.
Authentication
The authentication workflow involves Equativ’s authentication provider (Auth0) and Equativ’s own Maestro user API.
Required information
To authenticate and use the Maestro Reporting API, you need the following credentials, which will be provided by your Equativ contact:
- the
client_idandclient_secret - the Auth0 password
Treat any received credentials as confidential and don't share them with third parties.
Step 1: Request the access token from Auth0
Request the access token from Equativ’s authentication provider Auth0:
curl --request POST \
--url 'https://smartadserver.eu.auth0.com/oauth/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=http://auth0.com/oauth/grant-type/password-realm' \
--data 'realm=Username-Password-Authentication' \
--data 'audience=api.demand.smartadserver.com' \
--data-urlencode 'username={username}' \
--data-urlencode 'password={password}' \
--data 'client_id={client id}' \
--data 'client_secret={client secret}'In the response, you will receive the access token, which has a time to live of 10 hours (36000 seconds):
{
"access_token":"<access token>",
"expires_in": 36000,
"token_type": "Bearer"
}Step 2: Request the user token
With the access token obtained in Step 1, you must now request the user token, which you will use in all future API requests:
curl --request GET \
--url https://buyerconnectapis.smartadserver.com/authorize \
--header 'Authorization: Bearer <access token>'The response body will only contain the user token which has a time to live of 10 hours.
Step 3: Use the user token in API requests
Use the user token obtained in Step 2 in the Authorization header of all of your API requests:
curl --request GET \
--url https://buyerconnectapis.smartadserver.com/async-report \
--header 'Authorization: Bearer <user token>'Work with Maestro Reporting API
Endpoint
The endpoint for the Maestro Reporting API is: https://buyerconnectapis.smartadserver.com/async-report/
Best practices
As a general rule, make sure you spread report requests over time. Requesting multiple reports at the same time can quickly overwhelm the API. The API might slow down, become unreliable, or even become unavailable due to crashed servers.
Set the use case
For each report, you must specify the use case (field name: useCaseId). Each dimension and metric is associated with one or multiple use cases. Each use case corresponds to a View in the Maestro user interface (Instant Report Builder or Instant Insights).
The following table contains the use case names in the API and the corresponding view names in the Maestro user interface.
| Use case name #1 in Reporting API | Use case name #2 in Reporting API | View name in IRB/Instant Insights |
|---|---|---|
| demandcontentmetadata | ContentMetadata | Content Metadata |
| demandmediabuying | MediaBuying | Activation |
| demandprogrammatic | RTB | Programmatic |
| demandsegment | ForecastDMKP | Data Marketplace |
| scope3 | Sustainability |
For a complete example illustrating the useCaseId, see Example 3: Report with useCaseId mediaBuying.
Set the report name
To set a name for the report in the Maestro Reporting API, include the name field in the request. You can reuse the same name across different reports.
In this example, the report is named "Scheduled Report." You can change it to any name you prefer.
"name": "Scheduled Report",Set the time frame covered by the report
Use the StartDate and EndDate fields to define the time frame for your report.
- For one-time reports, use absolute and/or relative datetime.
- For scheduled reports, use relative datetime only, for example
"startDate": "CURRENT_DAY-2".
Set the report time units
You can add one or multiple time units to your report by adding the desired units in the dimensions object.
| Time unit | Snippet |
|---|---|
| Hourly | |
| Daily | |
| Monthly | |
Use time zones
You can use time zones with full hour offsets, such as UTC+6 or UTC-4. Time zones with a 30-minute offset are not supported. For example, you cannot use 'Indian Standard Time' (IST) because it has a 30-minute offset: UTC+05:30.
For the available time zones, see column "TZ database name" in the List of tz database time zones.
| Time zone | Snippet |
|---|---|
| Paris | |
| Tokyo | |
| Chicago | |
Set the report recipients
One-time and scheduled report can have one or more recipients. The report is always sent by e-mail with an enclosed .csv file.
| Recipients | Snippet |
|---|---|
| Single recipient | |
| Multiple recipients | |
Schedule a report
Add a scheduling section to generate a scheduled report that is generated on a regular basis. To configure the schedule, you need to use cron expressions. The crontab.guru editor can be useful to refine your expression.
Both a start and an end date must be set for your report, with the time span between them not exceeding six months. For example, if the start date is January 1, 2023, the latest possible end date is June 30, 2023.
| Report scheduling | Snippet |
|---|---|
| Scheduled report, covering the previous day, sent daily at 8 AM | |
| Scheduled report, covering the previous month, sent on the first day of each month at 6 AM | |
One-time report (no scheduling is defined), covering a specific week |
|
Reference
For the list of all available metrics and dimensions, see Report metrics and Report dimensions.
Complete report examples
The expected response will include the ID of the created report in UUID format in the response body, along with the HTTP status code 201 Created.
Example 1: Daily report covering the last 7 days
{
"startDate": "CURRENT_DAY-7",
"endDate": "CURRENT_DAY",
"name": "Scheduled Report",
"metrics": [
"buyerSpendEuro",
"companyVendorCostInEuro"
],
"dimensions": [
"hour",
"AuctionPackageExternalDealId"
],
"timezone": "Europe/Paris",
"dateFormat": "yyyy-MM-dd'T'HH:mm",
"postProcessingConfiguration": {
"emailConfigurations": [
{
"email": "Equativ@smartadserver.com",
"firstName": "equativ",
"lastName": "Equativ",
"organization": "Equativ"
}
]
},
"scheduling": {
"cronExpression": "0 2 * * *",
"startDate": "2022-12-13T16:25:12.2660273+00:00",
"endDate": "2022-12-16T16:25:12.2660323+00:00"
}
}
Example 2: One-time report
{
"startDate": "2022-06-29T18:22:15Z",
"endDate": "2022-06-30T07:04:55Z",
"name": "Advanced Report",
"metrics": [
"buyerSpendEuro",
"companyVendorCostInEuro",
"impressions",
"clicks",
"viewableImpressions",
"viewabilityRate",
"completionRate",
"audienceSegmentCostEuro",
"semanticSegmentCostEuro"
],
"dimensions": [
"AuctionPackageExternalDealId",
"AuctionPackageDealId",
"AuctionPackageDealName",
"appOrSiteDomain",
"partnerId",
"partnerName",
"externalSeatId",
"seatName",
"publisherId",
"publisherName",
"hour",
],
"timezone": "Europe/Paris",
"dateFormat": "yyyy-MM-dd'T'HH:mm",
"postProcessingConfiguration": {
"emailConfigurations": [
{
"email": "Equativ@equativ.com",
"firstName": "equativ",
"lastName": "Equativ",
"organization": "Equativ"
}
]
}
}
Example 3: Report with useCaseId mediaBuying
{
"startDate": "CURRENT_DAY-7",
"endDate": "CURRENT_DAY",
"name": "Scheduled Report",
"metrics": [
"buyerSpendEuro"
],
"dimensions": [
"lineItemId"
],
"timezone": "Europe/Paris",
"dateFormat": "yyyy-MM-dd'T'HH:mm",
"postProcessingConfiguration": {
"emailConfigurations": [
{
"email": "Equativ@smartadserver.com",
"firstName": "equativ",
"lastName": "Equativ",
"organization": "Equativ"
}
]
},
"scheduling": {
"cronExpression": "0 2 * * *",
"startDate": "2022-12-13T16:25:12.2660273+00:00