Skip to content
Visit Analytics on GitHub
Set theme to dark (⇧+D)

Querying basics

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

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

where the 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 you must include the limit argument, which can be equal or 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        }      }    }  }}

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