GraphQL Reporting API Overview

The GraphQL Reporting API is the place to retrieve all of your 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 NextRoll 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 configure it to use either Personal Access Tokens or OAuth.

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 -H 'Authorization: Token YOUR_TOKEN' \
    -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