Reporting and Listing API Request Details

PubMatic API platform uses a  consistent format for query parameters to the Reporting and Listing API. Each query requires a start and end date. You may also supply additional query parameters such as dimensions, metrics, filters and sort order to refine your query.

This can be used with reporting and listing requests. Listing requests are served by the respective resource end points such as /deals, /flights, /insertionOrders and so on.

Query Parameters Summary

The following table summarizes the all the query parameters accepted by the Core reporting API. Click each parameter name for a detailed description.

fromDate

Required for all reporting data requests must specify a date range. If you do not include fromDate and toDate parameters in the request, the server returns an error. Date values should be for a specific date by using the pattern YYYY-MM-DD.
Example, fromDate=2014-01-01

toDate

Required for all reporting data requests must specify a date range. If you do not include fromDate and toDate parameters in the request, the server returns an error. Date values should be for a specific date by using the pattern YYYY-MM-DD.
Example, XA toDate=2014-01-31

Dimensions

Optional.The dimensions parameter breaks down metrics by common criteria; for example, by siteId or  campaginId  While you can ask for the total number of impressions to your site, it might be more interesting to ask for the number of impressions broken down by site. In this case, you'll see the number of impressions from all sites.
Example, dimensions=sitId,campaginId

Metrics

Optional. The aggregated statistics of various entities such as impressionCount, bid requests etc. If a query has no dimensions parameter, the returned metrics provide aggregate values for the requested date range. However, when dimensions are requested, values are grouped  by dimension value. For example impressionCount requested with siteId returns the total impressionCount per site.
If a query has no metrics then all metrics will be available in response.
Example, metrics=impressionCount,zeroBid

Sort

Optional. A list of metrics and dimensions indicating the sorting order and sorting direction for the returned data.
Sorting direction defaults to ascending and can be changed to descending by using a minus sign (-) prefix on the requested field.
Sorting the results of a query enables you to ask different questions about your data. For example, to address the question "What are my top sites, and which impressionsCount do they provide most with less zero bids?" you can make a query with the the following parameter.
Example, sort=-impressionCount,zeroBid
 

Filters

Optional. The filters query string parameter restricts the data returned from your request. To use the filters parameter, supply a dimension or metric on which to filter, followed by the filter expression. For example, the following query requests impressionCount  grater than 10000  served by campaign name starts with the string xyz or end with abc.

&filters=impressionCount gt 10000&filters=campaignName like xyz*, campaignName like *abc

Filter Syntax

A single filter uses the form:

name operator value
In this syntax:

name - the name of the dimension or metric to filter on. Example, campaignName filters on the impressionCount metric.
operator - defines the type of filter match to use. Operators are specific to either dimensions or metrics.
value - states the values to be included in or excluded from the results.In case of String * character supported to find like query and all % character will be ignored.
There should be space between name, operator and value

Filter Operators