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

To authenticate with the Reporting API, follow the steps described in Maestro API authentication.

Work with Maestro Reporting API

Endpoint

The endpoint for the Maestro Reporting API is: https://demand-api.eqtv.io/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.

Dimensions and metrics

Refer to the following articles for dimension and metric names and descriptions:

• Report metrics  
• Report dimensions 

For dimensions, the following restrictions apply:

• Each report must have one primary dimension.
• Mixing unrelated dimensions is not supported. For example, you can't combine Deal with Publisher or Day.
• Acceptable combinations include the following:
  • Deal name and Deal Id
  • Primary dimension and select metrics, such as auctions, impressions, or vendor margin.

Available statuses

The following are the possible statuses of a report as it progresses through the processing pipeline.

• None
• PubSubPublishPending
• PubSubPublishSuccessful
• PubSubPublishFailed
• ReportGenerationPending
• ReportGenerationProgressing
• ReportPreviewReady
• ReportGenerationSuccessful
• ReportGenerationFailed
• PostProcessingProgressing
• PostProcessingSuccessful
• PostProcessingFailed
• Purged
• ReportGenerationTimeout
• ReportArchived 

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. 

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 date format per field

You can specify a date format per field. For example, request the Day dimension in the format YYYY-mm-dd, as follows:

{
    "Field": "Day",
    "DateFormat": "YYYY-MM-dd"
  }  
 

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.

"dimensions": [
           "hour"
           ],

"dimensions": [
           "day"
           ],

"dimensions": [
            "month"
            ],

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.

"timezone": "Europe/Paris",

"timezone": "Asia/Tokyo",

"timezone": "America/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.

"emailConfigurations": [
      {
        "email": "john.doe@client.com",
        "firstname": "John",
        "lastname": "Doe",
        "organization": "Client"
      }
    ]

"emailConfigurations": [
      {
        "email": "john.doe@client.com",
        "firstname": "John",
        "lastname": "Doe",
        "organization": "Client"
      },
      {
        "email": "jane.poe@agency.com",
        "firstname": "Jane",
        "lastname": "Poe",
        "organization": "Agency"
      }
    ]

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. 

The following table contains various report schedule configurations. The descriptions explain which time frame each report covers, and when and how often a report is generated.  

"startDate": "CURRENT_DAY-1",
"endDate": "CURRENT_DAY",
"scheduling": {
   "StartDate": "2022-11-24T00:00:00Z",
   "EndDate": "2023-01-17T00:00:00Z",
   "cronExpression": "0 8 * * *"
}

"startDate": "CURRENT_MONTH-1",
"endDate": "CURRENT_DAY-1",
"scheduling": {
   "StartDate": "2022-11-17T00:00:00Z",
   "EndDate": "2023-03-25T00:00:00Z"
   "cronExpression": "0 6 1 * *",
}

"StartDate": "2022-11-24T00:00:00Z",
"EndDate": "2022-11-17T00:00:00Z",

Consolidation of reporting data for previous day

The consolidation of reporting data for any given day is completed within the first 6 hours (UTC) of the following day. Generating a report before the consolidation is completed leads to incomplete reporting data for the previous day. For instance, if you set up a scheduled report with "frequency": "DAILY" and "period": "PREVIOUS_DAY", make sure you set the UTC time in  "schedulingStartDate" to a value no earlier than T06:00:00 (for instance: "schedulingStartDate": "2024-10-16T06:00:00").

Modify the output name of a field (dimension/metric)

You can specify an output name for any field (dimension/metric). In the final retrieved report, the field will have the specified output name, instead of the field’s default name.

The special characters , ) ( & ; - are prohibited in the outputName field. Using such characters will result in an error.

The sample below shows how to change the dimension name Day to Day new name. Additionally, the metric name Impressions is changed to Ad Impressions.

{  
"reportName": "doc_sample_4_output_names",
    "startDate": "2025-11-09T00:00:00",
    "endDate": "2025-11-10T00:00:00",
      "dimensions":[
        {
            "field": "Day",
            "outputName": "Day new name"
        }
       ],
       "metrics":[
         {
            "field": "Impressions",
            "outputName": "Ad Impressions"
        },
        {
            "field": "Clicks"
        }

       ],
       "useCaseId": "demandProgrammatic",
       "onFinishEmails": ["example@example.com"]
}

Data transfer to AWS S3 bucket

If you are using Amazon Web Services' (AWS) Simple Storage Service (S3), you can have your report data transferred and stored directly in your own S3 bucket.

Process

Take the following steps to use this service:

1. Send credentials: Send the credentials of your AWS S3 bucket to your service contact at Equativ. The service team will register the credentials in Equativ's secure databases.
2. Retrieve CredentialsId: Based on the credentials you provided, Equativ's service team generates the CredentialsId and sends it to you.
3. Add and configure DataTransfer object: Add the DataTransfer object to your report configuration with the appropriate parameters. 
4. Request report: Finalize the report configuration and request the report.
5. Get report data from S3 bucket: If the data transfer is successful, retrieve the report data from your S3 bucket for further processing.

Add DataTransfer object

Endpoint

POST /async-report-gcp

DataTransfer object 

Add the DataTransfer object to the postProcessingConfiguration, next to the existing email configuration:

"postProcessingConfiguration": {
  "emailConfigurations": [
    { "email": "user@equativ.com" }
  ],
  "dataTransfer": {
    "credentialsId": "00000000-0000-0000-0000-000000000000",
    "additionalPath": "my-team/reports"
  }
}

Fields

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@equativ.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",
    "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"
      }
    ]
  }
}