Reporting API Overview

Warning

The Reporting API will be retired at the end of February 2022. Please migrate to the GraphQL Reporting API by following the migration guide.

Authentication

For details on how to authenticate, refer to Get Started with the NextRoll API.

Getting Started

The reporting API endpoints are divided into two categories: JSON endpoints and CSV export endpoints.

JSON endpoints are designed for use in dashboard contexts. Each endpoint corresponds to a specific type of object breakdown (e.g. by advertisable, adgroup, or ad), and allows the response to contain a breakdown by that object, by day, or both. This corresponds to a typical dashboard page’s object table and time series graph, respectively.

CSV export endpoints are designed for use by custom reports. These endpoints return data in CSV format with a header to describe the schema.

Currency conversions

All cost and revenue numbers are returned with two decimal places of precision. The default currency is US Dollars (USD), and can be overridden with the currency query parameter where appropriate.

Attributions

An attribution is a user-defined conversion event with its attributed impression(s) or click(s). There are two classes of attributions:

  1. Standard attributions are generated to be either click-through or view-through attributions. This determination is done by using the advertiser’s click-through and view-through windows, which are specified in the advertiser’s account settings.

  2. Flexible attributions behave more like potential attributions. These attributions do not have any concrete meaning without specifying click-through and view-through windows post-generation of the attribution. The advantages of flexible attributions are that they allow the user to experiment with different windows, and they also contain the full 30-day window of impression and click history.

There are correspondingly two sets of endpoints for attribution reporting: one for standard attributions, and one for flexible attributions. The endpoints for standard attributions provide summarized counts for click-through and view-throughs, along with their associated revenues. The endpoints for flexible attributions provide more raw-level data for impression and click history, so as to allow the user to efficiently explore the resulting data set without having to make a series of calls.

Note

Entity responses will be an empty JSONArray if there are no metrics available for the specified date ranges and there are no URL filter params specified other than the advertisable_eid.

Deliveries

Deliveries are aggregated counts of impressions and clicks, along with their associated costs.

Note

Entity responses will be an empty JSONArray if there are no metrics available for the specified date ranges and there are no URL filter params specified other than the advertisable_eid.

Segments

Segment deliveries are aggregated counts of visitors and revenue.

Note

Entity responses will be an empty JSONArray if there are no metrics available for the specified date ranges and there are no URL filter params specified other than the advertisable_eid.