Reporting Platforms Guide¶
If you’re an analytics platform interested in supporting AdRoll and RollWorks customers, this is the guide for you.
If you’re interested in partnering with us, send the partnerships team an email. If you have any API questions, you can contact the API team.
Get to know the NextRoll API¶
Before you start building your integration, it helps to have a basic understanding of the NextRoll API.
Get Started with the NextRoll API will help you make your first API call.
Get to know NextRoll provides an overview of the object structure and defines common terminology.
AdRoll and RollWorks similarities¶
You can use the NextRoll API for both AdRoll and RollWorks customers. When building an integration to support both customer types, there are more similarities than differences.
Most metrics customers are interested in relate to campaigns and their components: AdGroups, Ads, and Audiences. Campaigns can run on the Web, Facebook, and LinkedIn. Both AdRoll and RollWorks customers run campaigns on the Web. AdRoll customers also tend to run Facebook campaigns, while RollWork customers often run LinkedIn campaigns.
Both AdRoll and RollWorks customers can run Universal Campaigns. Universal Campaigns are a particular campaign type that abstracts multiple inventory campaigns (i.e., Web, Facebook) under a single budget.
You can retrieve reporting data aggregated by Universal Campaign or retrieve metrics for the inventory campaigns within the Universal Campaign. By default, the GraphQL Reporting API will not return the aggregated Universal Campaign metrics. It will return the inventory campaigns. We recommended setting the query flag “enableUniversalCampaigns “to “true “so that queries for campaigns return Universal Campaign objects.
RollWorks differences¶
RollWorks customers can run Playbooks, a simple user experience for running B2B advertising campaigns that typically consist of two Universal Campaigns. In the RollWorks dashboard, we show aggregate metrics for a Playbook and the Universal Campaigns within the Playbook.
The GraphQL Reporting API doesn’t support querying for a Playbook directly. You’ll first need to query for all campaigns in an Advertisable. Then you’ll aggregate the campaign metrics in your application. You can use the “playbookEID “and “playbookName “fields to see which campaigns are associated with a Playbook.
AdRoll and RollWorks customers will also use different Audience (aka Segment) types. AdRoll customers primarily use URL Audiences. RollWorks customers primarily use Target Account Lists. The Web domain represents an Account for the targeted company. RollWorks customers will look for metrics aggregated at the Account level. For example, a RollWorks customer would want to know, “how many impressions have I served to each account I’ve targeted?”
Authentication¶
Use OAuth 2.0 to gain access to a user’s account. Our OAuth 2.0 implementation is compatible with standard libraries. You should be able to plug in our token and authorization URLs into your favorite library. The flow is identical for both AdRoll and RollWorks customers.
Note
OAuth refresh tokens expire after use. You’ll receive a new refresh token along with your new access token.
See also:
Retrieve Metrics¶
To retrieve reporting data, you use the GraphQL Reporting API. You can browse the schema and experiment with building queries using the GraphQL Reporting API console.
The primary metrics customers are interested are delivery and attribution metrics. We offer this data at multiple levels of granularity:
Note
For readability and reuse, our examples use GraphQL’s variables and fragments features. See Reusable queries for an example of how to use these features.
See also:
Advertisables for user¶
Before you start retrieving metrics, you’ll need to query for the list of Advertisables the user has access to this can be done with this query:
query AdvertisablesForUser {
organization {
current {
advertisables {
eid
name
}
}
}
}
Related types: Organization, Advertisable
Metrics for Advertisables¶
For a subset of customers that deal with many Advertisables, it may be helpful to query for metrics at the Advertisable level. For example, an agency may want to see top-level metrics across their clients.
query MetricsForAdvertisables($advertisables: [String!]!, $startDate: Date, $endDate: Date) {
flags(enableUniversalCampaigns: true)
advertisable {
byEIDs(eids: $advertisables) {
eid
name
metrics(start: $startDate, end: $endDate) {
byDate {
date
# Deliveries
cost
impressions
clicks
ctr
cpm
cpc
# Attribution
conversions
cpa
clickThroughs
clickCPA
viewThroughs
viewCPA
}
}
}
}
}
Related types: Advertisable, MetricForAdvertisable
Metrics for Campaigns¶
An Advertisable can contain many campaigns, so we recommended fetching the list of campaigns for the Advertisable first. Then you can query campaign metrics in batches.
query CampaignsForAdvertisable($advertisable: String!) {
flags(enableUniversalCampaigns: true)
advertisable {
byEID(advertisable: $advertisable) {
campaigns {
eid
name
type
channel
# RollWorks Playbooks
playbookEID
playbookName
playbookType
}
}
}
}
The following query fetches campaign-level metrics for a list of Campaign EIDs for the specified date range.
query MetricsForCampaigns($campaigns: [String!]!, $startDate: Date, $endDate: Date) {
flags(enableUniversalCampaigns: true)
campaign {
byEIDs(eids: $campaigns) {
eid
name
# RollWorks Playbooks
playbookEID
playbookName
playbookType
metrics(start: $startDate, end: $endDate) {
byDate {
date
# Deliveries
cost
impressions
clicks
ctr
cpm
cpc
# Attribution
conversions
cpa
clickThroughs
clickCPA
viewThroughs
viewCPA
}
}
}
}
}
Related types: Advertisable, Campaign, MetricForCampaign
AdGroup metrics for a campaign¶
Campaigns can contain one or more AdGroups. The following query fetches metrics for all AdGroups in the specified Campaign EIDs.
If the number of AdGroups in the campaign is large, you should fetch all AdGroups in the Campaign and then query AdGroup metrics in batches.
query MetricsForAdGroups($campaigns: [String!]!, $startDate: Date, $endDate: Date) {
flags(enableUniversalCampaigns: true)
campaign {
byEIDs(eids: $campaigns) {
eid
name
adgroups {
eid
name
metrics(start: $startDate, end: $endDate) {
byDate {
date
# Deliveries
cost
impressions
clicks
ctr
cpm
cpc
# Attribution
conversions
cpa
clickThroughs
clickCPA
viewThroughs
viewCPA
}
}
}
}
}
}
Ad metrics for a campaign¶
Ad metrics exist within the Adgroup object. Campaigns can have many AdGroups, and each AdGroup can have many Ads. If the number of Ads or AdGroups is small, you can query for everything in a single API call.
If the number of AdGroups or Ads in the campaign is large, you should fetch all AdGroups in the Campaign and then query Ad metrics in batches.
query MetricsForAds($campaigns: [String!]!, $startDate: Date, $endDate: Date) {
flags(enableUniversalCampaigns: true)
campaign {
byEIDs(eids: $campaigns) {
eid
name
adgroups {
eid
name
ads {
eid
name
adFormatName
channel
metrics(start: $startDate, end: $endDate) {
byDate {
date
# Deliveries
cost
impressions
clicks
ctr
cpm
cpc
# Attribution
conversions
cpa
clickThroughs
clickCPA
viewThroughs
viewCPA
}
}
}
}
}
}
}
Account metrics for a campaign¶
For RollWorks customers, their campaigns target Account Lists. Account Lists are represented as Web domains for the companies the campaign is targeting. You can fetch delivery and attribution data aggregated by the targeted Account (aka domain).
query MetricsForAccount($advertisable: String!, $campaigns: [String!]!, $startDate: Date!, $endDate: Date!) {
accountMetrics {
summary(advertisableEID: $advertisable, campaignEIDs: $campaigns, start: $startDate, end: $endDate) {
domain
# Deliveries
cost
impressions
clicks
# Attribution
adjustedClickThroughs
adjustedViewThroughs
}
}
}
Related types: FieldAccountMetrics
Optimizing queries¶
Paginate your queries¶
Due to the ability to query child objects and large date ranges, it’s easy to query many fields in a single request. These queries can cause timeouts or other issues. Here are a few suggestions on how to avoid fetching too much data in a single request.
Here are pitfalls to avoid:
Don’t query multiple levels of nested objects. For example, don’t fetch all Advertisables, their Campaigns, and their AdGroups in a single request.
For Campaigns, don’t fetch metrics for all AdGroups in a single request
For AdGroups, don’t fetch metrics for all Ads in a single request
To improve query performances, you can use the following pagination approaches:
Paginate by querying a subset of objects. First, query for a list of EIDs and then query the objects directly. For example, query for all Campaigns in an Advertisable, then query for Campaign metrics in batches.
Paginate by querying a subset of dates. For example, instead of querying for six months of daily reports in a single request, make six requests that query for a month at a time.
Reusable queries¶
GraphQL has convenience features that enable you to reduce code and reuse queries. You can
In this example query, we retrieve the metrics most users want.
Warning
This query will only work for customers with a small number of objects.
query AllAdvertisables($startDate: String, $endDate: String) {
advertisable {
forUser {
eid
name
campaigns {
eid
name
type
metrics(start: $startDate, end: $endDate) {
byDate {
date
...campaignPerfMetrics
...campaignConversionMetrics
}
}
}
adgroups {
eid
name
metrics(start: $startDate, end: $endDate) {
byDate {
date
...performanceMetrics
...conversionMetrics
}
}
audiences {
eid
name
type
metrics(start: $startDate, end: $endDate) {
summary {
...audienceMetrics
}
}
}
}
ads {
eid
name
metrics(start: $startDate, end: $endDate) {
byDate {
date
...performanceMetrics
...conversionMetrics
}
}
}
}
}
}
fragment campaignPerfMetrics on MetricForCampaign {
cost
impressions
clicks
ctr
cpm
cpc
}
fragment campaignConversionMetrics on MetricForCampaign {
conversions
cpa
clickThroughs
clickCPA
viewThroughs
viewCPA
}
fragment performanceMetrics on Metric {
cost
impressions
clicks
ctr
cpm
cpc
}
fragment conversionMetrics on Metric {
conversions
cpa
clickThroughs
clickCPA
viewThroughs
viewCPA
}
fragment audienceMetrics on AudienceMetric {
audienceSizeTotal
audienceSizeCurrent
audienceSizeInDateRange
}
Example variables:
{
"startDate": "2017-12-09",
"endDate":"2017-12-10"
}
You combine the above query and variables into a JSON POST request:
POST /reporting/api/v1/query HTTP/1.1
Host: services.adroll.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
{
"query": "....",
"operationName": "AllAdvertisables",
"variables": { "startDate": "2017-12-09", "endDate":"2017-12-10" }
}
The response with be a JSON object that mirrors the structure of the input query:
{
"data": {
"advertisable": {
"forUser": [
{
"eid": "C5355E63986CA41AA7207F",
"name": "Test Advertisable",
"adgroups": [],
"ads": [
{
"eid": "7588D18F396772CED83501",
"name": "160x600",
"metrics": {
"byDate": [
{
"clickCPA": null,
"clickThroughs": null,
"clicks": null,
"conversions": null,
"cost": null,
"cpa": null,
"cpc": null,
"cpm": null,
"ctr": null,
"date": "2017-12-09",
"impressions": null,
"viewCPA": null,
"viewThroughs": null
}
]
}
}
],
"campaigns": [
{
"eid": "A48AAB0081005DDB968258",
"name": "My Facebook Retargeting Campaign",
"type": "retargeting",
"metrics": {
"byDate": [
{
"clickCPA": null,
"clickThroughs": null,
"clicks": null,
"conversions": null,
"cost": null,
"cpa": null,
"cpc": null,
"cpm": null,
"ctr": null,
"date": "2017-12-09",
"impressions": null,
"viewCPA": null,
"viewThroughs": null
}
]
}
}
]
}
]
}
},
"(~˘▾˘)~": "2017.12.11-1/req160053",
"request": "req160053",
"version": "2017.12.11-1"
}