Required Parameters

There are 5 required parameters needed to make a successful request to the Custom Reporting API.

start: This is a date string that follows the ISO date format, i.e. 2021-08-10T19:00:00Z (This value is INCLUSIVE, meaning items matching it are included in the response.)
end: This is a date string that follows the ISO date format, i.e. 2021-08-10T20:00:00Z (This value is EXCLUSIVE, meaning items matching it are NOT included in the response. )
metrics: This should be a comma separated string, i.e. ‘requests,impressions’
dimensions: This should be a comma separated string, i.e. ‘endpoint,country,demandPartnerId’
granularity: This is the level of granularity for returned data, i.e. "hour", "day", "month".

⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼

Query Notes

For the start and end parameters, please request in UTC (providing the “Z” at the end for the offset). Specifying a timezone is a future feature. Also, please only request one hour, one day, or one month in a request. The endpoints will automatically determine which data aggregation to use.

Granularity

There are limitations in place for how much data you can request, depending on the type of granularity provided in the request. We have the following data available for each granularity:

hour:for the past 45 days
day: for the past 2 years
month:starting with January 2017
Note: many of our dimensions are not available back to 2017, most are available starting in 2022.

You cannot request all of the available data for a granularity in one request. The limitations in one request are:

hour: minimum of 1 hour, maximum of 24 hours
day: minimum of 1 day, maximum of 1 month (depending on the month, this can range from 28 days to 31 days)
month: minimum of 1 month, maximum of 1 year

Possible Values

The following values are temporarily unavailble: requests, requestsWithBid, fill rate, zoneId, zoneSize, zoneName.

Metrics:

requests
requestsWithBid
impressions
publisherRevenue
fillRate
cpm

Dimensions:

auction - Traffic generated from (e.g Header Bidding, Google OB, Amazon TAM, Waterfall, ORTB, Nimbus, SpringServe, Publica, BidMachine)
zoneId - Unique ID associated to a Sovrn ad tag
zoneSize - Size of that zone (e.g 728x90)
zoneName - Unique name given to that ID within the account (ex. RON_728x90)
country - Country of generated traffic (e.g. us, ca, de)
demandPartner - DSP (e.g TradeDesk)
seatId - DSP seat, its an identifier for the Advertiser/advertiser group that is placing creatives
dealId - Deal info, used to identify deals and their performance
advertiser - The url of the advertiser (e.g Nike.com)
adType - Format in which an ad was served (e.g video, display)
device - Type of device where an ad was served (e.g smartphone, tablet, desktop)
browser - Browser in which an ad was served (e.g Chrome, Firefox, Safari)
domain - Domain in which the ad was served on (e.g www.sovrn.com). (If domain is included in the query, all reporting data will be for the provided domain. If not included, all domains will be included).
bundleId - The application bundle ID for the property. Sometimes referred to as the package ID.
propertyType - Type of property (web or app)