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.
Swagger UI
You can use the Swagger UI to explore and test the API endpoints interactively.
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.
Authentication workflow
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), which can take one of the two values:
-
rtb: for report fields related to Auction Package deals -
mediaBuying: for report fields related to campaigns and line items
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 | |
One-time and scheduled reports
Reports can be generated as:
- One-time reports: these are reports without a scheduling section.
- Scheduled reports: these reports are generated and sent on a regular basis and are configured with a scheduling section, as described in section "Schedule a report".
Schedule a report
You can schedule reports to be generated and sent automatically on a recurring basis. To configure the schedule, you need to use cron expressions. You can use the crontab.guru editor for testing and refining your expressions.
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