User Lists API Reference

Note

If you use the APIs provided here, you are subject to the API Terms of Use, and Service Privacy Notice

Note

We’ve introduced API keys, please read Migrating to API Keys

Description

AdRoll User List API 1.0

Access your user list data with Adroll User List API

Operations

GET /user-lists/api/v1/userlists/ad

Provides user list sizes broken down by ad and date

Parameters:

Query Parameters

Name

Required

Type

Description

breakdowns

True

string

Comma-separated list of breakdowns. Must be at least one of entity, date, summary

advertisable_eid

True

string

A single advertisable EID

ad_eids

True

string

Comma-separated list of ad EIDs

durations

True

string

Comma-separated list of ad durations. Must be the same length as ad_eids

start_date

False

string

Start of the date range in yyyy-MM-dd or MM-dd-yyyy format (inclusive)

end_date

False

string

End of the date range in yyyy-MM-dd or MM-dd-yyyy format (exclusive)

past_days

False

integer

Equivalent to setting end_date to today (exclusive) and start_date to (today - past_days). Takes precedence over start_date and end_date

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

successful operation

Returns UserList-Metrics-Response

400

Ad EID is invalid

404

Ad data is missing

GET /user-lists/api/v1/userlists/adgroup

Provides user list sizes broken down by AdGroup and date

Parameters:

Query Parameters

Name

Required

Type

Description

breakdowns

True

string

Comma-separated list of breakdowns. Must be at least one of entity, date, summary

advertisable_eid

True

string

A single advertisable EID

adgroup_eids

True

string

Comma-separated list of AdGroup EIDs

durations

True

string

Comma-separated list of ad durations. Must be the same length as ad_eids

start_date

False

string

Start of the date range in yyyy-MM-dd or MM-dd-yyyy format (inclusive)

end_date

False

string

End of the date range in yyyy-MM-dd or MM-dd-yyyy format (exclusive)

past_days

False

integer

Equivalent to setting end_date to today (exclusive) and start_date to (today - past_days). Takes precedence over start_date and end_date

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

successful operation

Returns UserList-Metrics-Response

404

AdGroup data is missing

GET /user-lists/api/v1/userlists/advertisable

Provides user list sizes broken down by advertisable and date

Parameters:

Query Parameters

Name

Required

Type

Description

breakdowns

True

string

Comma-separated list of breakdowns. Must be at least one of entity, date, summary

advertisable_eid

True

string

A single advertisable EID

durations

True

string

Comma-separated list of ad durations. Must be the same length as ad_eids

start_date

False

string

Start of the date range in yyyy-MM-dd or MM-dd-yyyy format (inclusive)

end_date

False

string

End of the date range in yyyy-MM-dd or MM-dd-yyyy format (exclusive)

past_days

False

integer

Equivalent to setting end_date to today (exclusive) and start_date to (today - past_days). Takes precedence over start_date and end_date

use_uhura

False

boolean

Explicitly ask the API to use the Uhura Backend for hll calculations

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

successful operation

Returns UserList-Metrics-Response

GET /user-lists/api/v1/userlists/segment

Provides user list sizes broken down by segment and date

Provides user list sizes broken down by segment and date, as well as a summary for counts across all specified segments. If a particular segment has multiple durations associated with it, then the summary section will be computed with the segment’s largest duration. This endpoint also allows the specification of excluded segments, which are segments to not consider in generating the user list sizes. The excluded segments and their durations are combined together across the entire specified date range when they are being applied against the summary and entity breakdowns, but they are applied on a corresponding day-by-day basis when applied to the date breakdown.

Parameters:

Query Parameters

Name

Required

Type

Description

breakdowns

True

string

Comma-separated list of breakdowns. Must be at least one of entity, date, summary

advertisable_eid

True

string

A single advertisable EID

segment_eids

True

string

Comma-separated list of segment EIDs

durations

True

string

Comma-separated list of ad durations. Must be the same length as ad_eids

excluded_segment_eids

False

string

Comma-separated list of segment EIDs to exclude from the count

excluded_durations

False

string

Comma-separated list of durations corresponding to the segments to exclude from the count. Must be the same length as excluded_segment_eids. Each excluded segment must have exactly one duration associated with it.

start_date

False

string

Start of the date range in yyyy-MM-dd or MM-dd-yyyy format (inclusive)

end_date

False

string

End of the date range in yyyy-MM-dd or MM-dd-yyyy format (exclusive)

past_days

False

integer

Equivalent to setting end_date to today (exclusive) and start_date to (today - past_days). Takes precedence over start_date and end_date

use_uhura

False

boolean

Explicitly ask the API to use the Uhura Backend for hll calculations

email

False

boolean

Boolean representing whether or not the segment email hll endpoint should be queried.

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

successful operation

Returns UserList-Metrics-Response

POST /user-lists/api/v1/userlists/segment

Provides user list sizes broken down by segment and date

This is identical to the GET endpoint, but is presented as a POST endpoint in order to submit large input sets. The POST body is a JSON-encoded string whose format follows from the GET endpoint’s query parameters.

Parameters:

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Schema for request body: Segment-UserList-Post-Input

{
  "advertisable_eid": "string",
  "breakdowns": [
    "string"
  ],
  "durations": [
    0
  ],
  "end_date": "string",
  "excluded_durations": [
    0
  ],
  "excluded_segment_eids": [
    "string"
  ],
  "past_days": 0,
  "segment_eids": [
    "string"
  ],
  "start_date": "string"
}

Responses:

200

successful operation

Returns UserList-Metrics-Response

Definitions

UserList-Metrics-Response

An object for responding to requests with UserList metrics

Type

object

results
Type

UserList-Metrics

UserList-Metrics

An object for the different ways UserList metrics are broken down and exposed

Type

object

summary
Type

UserList-Summary-Metrics-Response

entity
Type

array of User-List-Entity-Metrics-Response

date
Type

array of UserList-Date-Metrics-Response

UserList-Summary-Metrics-Response

A JSON encoded wrapper for UserList Metrics

Type

object

new_visitors

Count of unique new visitors who visited the entities between the specified date range. DEPRECATED.

Type

integer

Format

int64

total_visitors

Total number of unique visitors between the specified start_date (inclusive) and end_date (exclusive) ignoring duration i.e. [START_DATE, END_DATE)

Type

integer

Format

int64

current_visitors

Total number of unique visitors within the duration of the entity i.e. [$TODAY - $DURATION, $TODAY)

Type

integer

Format

int64

current_visitors_in_date_range

Total number of unique visitors within the duration of the entity with the specified date range i.e. [$END_DATE - $DURATION, $END_DATE)

Type

integer

Format

int64

excluded_total_visitors

Count of total visitors who did not visit entities because of a exclusion segment.

Type

integer

Format

int64

excluded_current_visitors

Count of current visitors at the time of query who did not visit entities because of a exclusion segment.

Type

integer

Format

int64

excluded_current_visitors_in_date_range

Count of current visitors during the end_date who did not visit entities because of a exclusion segment.

Type

integer

Format

int64

User-List-Entity-Metrics-Response

Response of userlist metrics broken down by a specified entity type

Type

object

entity

The EID of a specified entity type that belongs to the advertisable

Type

string

XX_days
Type

User-List-Entity-Duration-Metrics-Response

User-List-Entity-Duration-Metrics-Response
Type

object

new_visitors

Count of unique new visitors who visited the entities between the specified date range. DEPRECATED.

Type

integer

Format

int64

total_visitors

Total number of unique visitors between the specified start_date (inclusive) and end_date (exclusive) ignoring duration i.e. [START_DATE, END_DATE)

Type

integer

Format

int64

current_visitors

Total number of unique visitors within the duration of the entity i.e. [$TODAY - $DURATION, $TODAY)

Type

integer

Format

int64

current_visitors_in_date_range

Total number of unique visitors within the duration of the entity with the specified date range i.e. [$END_DATE - $DURATION, $END_DATE)

Type

integer

Format

int64

UserList-Date-Metrics-Response

A JSON encoded wrapper for UserList Metrics broken down by each day

Type

object

date
Type

string

Format

date-time

new_visitors

Count of unique new visitors who visited the entities between the specified date range. DEPRECATED.

Type

integer

Format

int64

total_visitors

Total number of unique visitors between the specified start_date (inclusive) and end_date (exclusive) ignoring duration i.e. [START_DATE, END_DATE)

Type

integer

Format

int64

excluded_total_visitors

Count of total visitors who did not visit entities because of a exclusion segment.

Type

integer

Format

int64

Segment-UserList-Post-Input

Parameters when sending a POST request to the segment user list endpoint

Type

object

breakdowns

List of breakdowns. Must be at least one of entity, date, summary

Required

True

Type

array of items

advertisable_eid

A single advertisable EID

Required

True

Type

string

segment_eids

List of segment eids

Required

True

Type

array of items

durations

List of segment durations. Must be the same length as segment_eids

Type

array of items

excluded_segment_eids

List of segment eids to exclude from the count

Type

array of items

excluded_durations

List of durations corresponding to the segments to exclude from the count. Must be the same length as excluded_segment_eids. Each excluded segment must have exactly one duration associated with it.

Type

array of items

start_date

Start of the date range in yyyy-MM-dd or MM-dd-yyyy format (inclusive)

Type

string

end_date

End of the date range in yyyy-MM-dd or MM-dd-yyyy format (exclusive)

Type

string

past_days

Equivalent to setting end_date to today (exclusive) and start_date to (today - past_days). Takes precedence over start_date and end_date

Type

integer

Format

int32

Bulk-UserList-Post-Input

Parameters when sending a POST request to the bulk user list endpoint

Type

object

entities
Required

True

Type

Bulk-Entity-Input

start_date

Start of the date range in yyyy-MM-dd or MM-dd-yyyy format (inclusive)

Type

string

end_date

End of the date range in yyyy-MM-dd or MM-dd-yyyy format (exclusive)

Type

string

past_days

Equivalent to setting end_date to today (exclusive) and start_date to (today - past_days). Takes precedence over start_date and end_date

Type

integer

Format

int32

Bulk-Entity-Input
Type

object

advertisable_eid

A single advertisable EID

Required

True

Type

string

segment_eids

List of segment eids

Type

array of items

adgroup_eids

List of adgroup eids

Type

array of items

ad_eids

List of ad eids

Type

array of items

durations

List of segment durations. Must be the same length as segment_eids

Type

array of items

Query-Response

An object for responding to requests with the metadata for reporting audience insights cookie attribute distribution by segment

Type

object

id

ID of the query metadata

Type

integer

advertisable_eid

A single advertisable EID

Type

string

attribute_name

Name of the attribute selected

Type

string

top_number

Number of attribute values to display

Type

integer

last_modified_date

Last time this set of metadata was modified, currently equates to creation date

Type

string

Results-Line

A single result line from the query

Type

object

id

ID of the query metadata

Type

integer

segment_eid

A single segment EID

Type

string

attribute_category

Value of the attribute selected

Type

string

date_analyzed

Date that this data pertains to

Type

string

cookies_matched

Number of cookies with a matched attribute value for this attribute

Type

integer

segment_size

Number of cookies in this segment

Type

integer

unique_cookies

Number of cookies with this attribute value

Type

integer

last_modified_date

Creation date of result data

Type

string

Results-Response
Type

object

results

List of result lines

Type

array of Results-Line

Results-Empty-Dates-Response
Type

object

results

List of dates ISO format

Type

array of items