Getting started

This section describes setting up authentication for GraphiQL and GraphQL Analytics API querying basics.

Setting up authentication in GraphiQL

To ensure that the GraphQL Analytics API authenticates your queries, retrieve your Cloudflare Global API Key.

To edit HTTP headers for authentication in GraphiQL:

  1. Launch GraphiQL

  2. Click Edit HTTP Headers  The Edit HTTP Headers window appears.

  3. Click Add Header

  4. Enter X-AUTH-EMAIL in the Header name field and your email address registered with Cloudflare in the Header value field, and click Save

  5. Click Add Header

  6. Enter X-AUTH-KEY in the Header Name field, paste your Global API Key in the _Header value _field, and click Save

  7. Click anywhere outside the Edit HTTP Headers window in GraphiQL to return to the Untitled Query 1 tab

  8. Enter https://api.cloudflare.com/client/v4/graphql in the GraphQL Endpoint field

The right-side response pane is empty if you entered your information correctly. An error displays if there are problems with your header credentials.

That's it! You’re ready to run queries using GraphiQL.

Querying basics

GraphQL structures data as a graph. You can explore the edges of the graph (using queries) to get the data you need. This is an example query format:

viewer {
      zones(filter:...) {
         requests(filter:...) {
           date, time, bytes,...
         }
      }
}

where viewer represents the initial node of the user running the query.

The viewer can access one or more zones (domains) or accounts. Each zone or account contains various data sets, such as HTTP requests for a zone. There are numerous metrics and dimensions about requests, such as the the response bytes or the time at which the requests were received. You can apply filters at each node.

This example query shows a range of GraphQL functionality. Two data sets for the specified zone are queried simultaneously, filters and aggregations are applied, and a limit is set on the number of records returned (note that the limit argument must be included and can be equal to up to 10,000).


query {
  viewer {
    zones(filter: {zoneTag: "<your zone ID>"}) {
      httpRequests1mGroups(limit: 5, filter: { datetime_gt: "2019-02-01T04:00:00Z", datetime_lt: "2019-02-01T06:00:00Z"}) {
        sum {
          countryMap {
            bytes
            clientCountryName
          }
        }
        dimensions {
          date
          datetime
        }
      }
      firewallEventsAdaptiveGroups(limit: 10, filter: { datetime_gt: "2019-02-01T04:00:00Z", datetime_lt: "2019-02-01T06:00:00Z"}) {
        count
        dimensions {
          clientCountryName
          clientAsn
          datetimeHour
        }
      }
    }
  }
}

This is only an example. You must specify the zoneTag for your domain. Your Cloudflare dashboard lists your Zone ID (zoneTag) on the Overview page.

How can you tell what data sets, metrics, dimensions, operators, and functions are available? One of the great features of a GraphQL API is that it offers "introspection": you can explore the graph (by making API calls) to see the available data sets, the fields and their types, and the operations you can perform. GraphiQL users this functionality to provide a "Documentation Explorer" that you can use to understand the schema. Click on the Docs link on the right-hand side and then drill down starting with Query and proceeding to viewer and then zone. Introspection is also used to provide query auto-complete and syntax validation.

Helpful Resources

Handy links for setting up the GraphQL Analytics API and learning about GraphQL.

Cloudflare specifc

General info on the GraphQL framework