AdRoll GraphQL Reporting API Overview

Warning

The GraphQL Reporting is in beta and the schema may change. Currently only campaign-level data is stable, all other data may be unstable. If you have questions or feedback, please contact the API team.

The AdRoll GraphQL Reporting API is the place to retrieve all of your AdRoll reporting data. Instead of making multiple API calls, you can retrieve everything you need in a single request. Want to query multiple Advertisables at once? That’s possible with the GraphQL Reporting Reporting API.

The GraphQL Reporting API replaces the following API methods:

What is GraphQL?

GraphQL is a query language for APIs. The benefits of GraphQL include:

  • Retrieve only the data you need
  • Access multiple resources at once
  • Evolve without API versions

If you’d like to learn the basics of GraphQL, we recommend reading the official Introduction to GraphQL.

Authentication

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

Getting Started

To make an API call, you’ll need to write a GraphQL query. Once you’ve written the query, you’ll package that query inside a JSON object. Then you’ll then send that JSON to POST /reporting/api/v1/query. GraphQL uses a single endpoint for all requests.

Alternatively, you could use a GraphQL client library. When using a client library, make sure you include your API key and HTTP basic authentication when making the request.

Your First Query

The following is GraphQL query retrieves the name and EID of every Advertisable you have access to:

query MyFirstQuery {
  advertisable {
    forUser {
      eid
      name
      campaigns {
        eid
        name
        metrics(start: "2017-06-01", end: "2017-06-30") {
          summary {
            impressions
            clicks
            cpc
            cpa
          }
        }
      }
    }
  }
}

This becomes the following JSON payload

{
   "query": "query MyFirstQuery { advertisable { forUser { eid name campaigns { eid name metrics(start: \"2017-06-01\", end: \"2017-06-30\") { summary { impressions clicks cpc cpa } } } } } }"
}

Which can then be sent using:

curl --user apihelp@adroll.com:password \
    -H 'Content-Type: application/json' \
    -d '{
       "query": "query MyFirstQuery { advertisable { forUser { eid name campaigns { eid name metrics(start: \"2017-06-01\", end: \"2017-06-30\") { summary { impressions clicks cpc cpa } } } } } }"
    }' \
    'https://services.adroll.com/reporting/api/v1/query?apikey=MYAPIKEY'

Which gives us our Advertisables:

{
  "(~˘▾˘)~": "2017.05.24-1/req4561",
  "request": "req4561",
  "version": "2017.05.24-1",
  "data": {
    "organization": {
      "current": {
        "advertisables": [
          {
            "eid": "B0167F8263EE64DEEEC533",
            "name": "Test advertisable",
            "metrics": {
              "summary": {
                "clicks": 100,
                "cpa": 1,
                "cpc": 1,
                "impressions": 200
              }
            }
          }
        ]
      }
    }
  }
}

Note

You can experiment with building queries using GraphiQL