AdRoll Reporting API Overview

Authentication

Authentication and authorization are done using AdRoll’s authentication service. Only HTTPS is supported. Authentication is performed using HTTP Basic Authentication. This ensures that access to any object (e.g. advertisable, segment, adgroup, ad, etc.) can occur only if the currently logged-in user has permission to do so.

API Methods

All endpoints are invoked with https://app.adroll.com/.

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 overriden with the currency query parameter where appropriate.

Attributions

An attribution is a customer-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 client 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. Unlike user lists, these counts are not uniques, but rather are a count of total distinct events.

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.

User Lists

User lists provide approximate sizes of sets. This is useful for determining metrics such as audience size. User lists can be computed at an Advertisable or Segment level.

User list metrics

These metrics are calculated by ignoring cookies which might have visited any excluded entities (if applicable).

Metric Description
total_visitors Total number of unique visitors between the specified start_date and end_date not looking at any duration value of the entities.
current_visitors Count of unique visitors who visit the entities during the specified date range. This value is calculated by counting all the users between end_date - duration days and the end_date.
new_visitors Count of unique new visitors who visit the entities between the specified date range. This value is calculated by looking back duration days from the start_date for the entity and excluding any visitors who visit the entity during that period.

Reporting API Change Policy

As stated in the Terms of Service, AdRoll may modifications to the API without advance notice. However, we will make commercially reasonable efforts to notify you of any changes through email and via updates to the Reporting API Release Notes.

For backwards-incompatible changes, we will give one month’s notice for affected features that are expected to have few to no users. For features that have heavy use, we will give three month’s notice.