How do I use the Sovrn Reporting API?

The Sovrn Custom Reporting API gives you programmatic access to your Ad Exchange performance data across web, Connected TV, and mobile app inventory — so you can pull reports into your own data warehouse, build custom dashboards, or automate analysis beyond what the Sovrn Platform UI offers. This guide walks you through getting set up and making your first request.

The full API reference lives in the Sovrn Developer Center.

Prerequisites

In order to utilize the Custom Reporting API, you must have:

• An active Sovrn Ad Exchange account.

• An API key. Generate one from your account at platform.sovrn.com/account/api-keys. You'll need both your Publisher ID and the API Key value.

Your API key is a 7-character prefix followed by a . and a 32-character UUID — for example: 1234567.a34d7eb0-abfc-44fea-9fcc-7es42be45663.

Step 1: Authenticate your request

Pass your API key in the request header using the key x-api-key:

x-api-key: 1234567.a34d7eb0-abfc-44fea-9fcc-7es42be45663

This header is required on every request. See the authorization reference for details.

Step 2: Build your query

Every request to the Custom Reporting API requires five query parameters:

• start — ISO 8601 datetime, inclusive (e.g., 2024-08-01T00:00:00Z). Items matching this timestamp are included in the response.

• end — ISO 8601 datetime, exclusive (e.g., 2024-08-02T00:00:00Z). Items matching this timestamp are not included.

• metrics — comma-separated list of metrics to return (e.g., impressions,publisherRevenue).

• dimensions — comma-separated list of dimensions to break the data out by (e.g., country,demandPartner).

• granularity — hour, day, or month.

All datetimes must be in UTC, indicated by the trailing Z. Specifying a timezone isn't currently supported.

Granularity rules

Each granularity has its own historical range and per-request window:

Most dimensions are only available from 2022 onward, so older months may return limited data.

Step 3: Choose your metrics

Available metrics:

• requests — Total ad requests*

• requestsWithBid — Requests that received bids*

• impressions — Total ads served successfully

• publisherRevenue — Your earnings after fees

• fillRate — Percentage of requests that result in an impression*

• cpm — Cost per thousand impressions

Step 4: Choose your dimensions

Available dimensions:

• auction — Traffic source (Header Bidding, Google OB, Amazon TAM, Waterfall, ORTB, Nimbus, SpringServe, Publica, BidMachine)

• zoneId — Unique ID for a Sovrn ad tag*

• zoneSize — Ad zone size, e.g., 728x90*

• zoneName — Unique name given to that zone, e.g., RON_728x90*

• country — Country of traffic (us, ca, de, etc.)

• demandPartner — DSP (e.g., TradeDesk)

• seatId — DSP seat identifier for the advertiser placing creatives

• dealId — Deal identifier

• advertiser — Advertiser URL (e.g., http://Nike.com )

• adType — Ad format (video, display, etc.)

• device — Device type (smartphone, tablet, desktop)

• browser — Browser (Chrome, Firefox, Safari, etc.)

• domain — Domain the ad was served on. If included, results are filtered to that domain; if omitted, all your domains are included.

• bundleId — Application bundle ID (sometimes called package ID)

• propertyType — web or app

*Temporarily unavailable: requests, requestsWithBid, fillRate, zoneId, zoneSize, zoneName.

Step 5: Make the request

A complete request looks like this:

curl --request GET \
--url 'https://api.sovrn.com/reporting/advertising/publishers/262681/account?start=2024-08-01T00%3A00%3A00Z&end=2024-09-02T00%3A00%3A00Z&metrics=publisherRevenue,impressions&dimensions=country,adType&granularity=day' \
--header 'x-api-key: prefix1.XXXXXXXX-YYYY-ZZZZ-AAAA-BBBBBBBBBBBB'

Replace 262681 with your Publisher ID, swap the date range, metrics, and dimensions for what you need, and update the x-api-key header with your real key.

URL-encode commas (%2C) and colons (%3A) in your query string. Refer to the Custom Reporting API reference for the complete list of available endpoint paths.

Rate limits

Two limits apply:

• 15 requests per minute, per API key. Exceeding this returns an error.

• 2,000 requests per 5 minutes, per IP address.

If you'll be pulling large volumes of data, batch your queries within these windows.

Data retention

The API stores data at three aggregation levels with different retention windows:

• Hourly — 10 days

• Daily — 2 years

• Monthly — indefinite

Daily and monthly aggregations are only available in UTC.

Troubleshooting

My request returns an authentication error. Confirm the header name is exactly x-api-key and that the value matches what's shown on your API Keys page in the Sovrn Platform.

I'm getting a "too many requests" error. You've hit the rate limit. Wait at least one minute before retrying, and reduce your request frequency.

My request returns less data than expected. Check that your time window doesn't exceed the per-request maximum for your chosen granularity. Also confirm the dimension you're querying has data available for that historical range.

Questions? Concerns? Our team would be more than happy to help. Reach out to our Support Team here.