Report Generation

The submit_delivery_report endpoint generates a report from impression and request data. These
reports are aggregated into discrete buckets of time, and are grouped by a subset of their
fields called dimensions. Data from fired impressions, alongside requests made to the exchange
server and requests that the exchange server makes, are collated to create the reports returned
by this endpoint.

The body of this request is broken up into roughly four conceptual parts, made up of six top
level fields.

Time Range fields:

These include start_date, end_date, and time_group. The start and end dates, which take
the format %Y-%m-%d %H:%M:%S determine the start and end of the time range the report will be
generated for. time_group represents how the report should partition the time.

For example: a start_date of "2023-09-20 05:00:00", an end_date of "2023-09-22 05:00:00",
and a time_group of hour will return 48 sets of values for the metrics and dimensions
requested. But if the time_group is changed to day, only 2 collections will be returned.

Dimensions

Represented by the dimensions key, Dimensions are any field on the report which, when taken
together, identify the data that metrics should be aggregated over. For (an
incomplete) example, if the supply_id, placement_id, domain, and country_code are all shared
between two reports, the metrics from those reports will be aggregated together.

The list of dimensions passed in through the dimensions key represents which of the
previously described dimensions to include in the returned report(s).

Metrics

Metrics are data aggregated across multiple chunks of reporting data for a given time period
and set of matching dimensions. Some examples of metrics over the given time period, and
matching dimensions include:

• number of outbound bid requests
• number of outbound bid responses
• number of inbound bid requests
• number of impressions
• avg bid price
• revenue

These metrics are aggregated differently depending on their type. {outbound | inbound} bid
{requests| responses}, and impressions are simple sums; avg bid price is an average taken across the queried
time period; revenue is the aggregation of impressions multiplied by their bid prices.

The metrics field in this request is a list of which of these Metrics to include in the
generated report(s).

Filters

📘

Info

Filters apply positively, meaning that any report which matches an expression WILL BE INCLUDED.

The filters field is an optional, user defined query that determines which data to
include in the report and to aggregate over. The value of filters deserves some special
attention.

At the top level, filters is an array of similarly structured query objects which represent
conditions . A simple example
of a query object might be:

{
  "domain": {
      "in": [
          "example.com",
          "kevel.com"
      ]
  }
}

Since reports which positively match the given filters are included this filter will cause the
report which have domains equal to either "example.com" or "kevel.com" to be included. In this
example, domain could have been any Dimension. The value corresponding to this is always
going to be in the form {operation: value(s)}. The operations all compare the value of the
dimension in the report to literal(s) given in value(s). The operations include:

• "eq": equal to (takes a single literal)
• "lt": less than (takes a single literal)
• "gt": greater than (takes a single literal)
• "lte": less than or equal to (takes a single literal)
• "gte": greater than or equal to (takes a single literal)
• "in": contained within a list of literals (takes a list of literals)

These operation: value pairs can also be combined. The desired {dimension: {domain: value(s)}} objects
can be wrapped in the logical operators "or" and "and". These top level keys take, as values, a
list of query objects. In the case of "or", if any of the queries match, the data will be
included; In the case of "and", they all must match. Right now, "or" is much more useful, since
"and" is the default behavior of having multiple {domain: value} pairs.

An example of using these logical operators might look like:

 {
     "or": [
         {
             "country_code": {
                 "in": [
                     1,
                     44,
                     351,
                     852
                 ]
             }
         },
         {
             "domain": {
                 "in": [
                     "example.com",
                     "kevel.com"
                 ]
             }
         }
     ]
 }