Cloudflare Docs
Analytics
Cloudflare Docs
Analytics
Search icon (depiction of a magnifying glass)
GitHub icon
Visit Analytics on GitHub
Set theme to dark (⇧+D)

Querying basics

​​ Structure of a GraphQL query

GraphQL structures data as a graph. GraphQL uses a schema to define the objects and their hierarchy in your data graph. You can explore the edges of the graph by using queries to get the data you need. These queries must respect the structure of the schema.

At the core of a GraphQL query is a node, followed by its fields. The node is an object of a certain type; the type specifies the fields that make up the object.

A field can be another node, in which case the appropriate query would contain nested elements. Some nodes look like functions that can take on arguments to limit the scope of what they can act on. You can apply filters at each node.

​​ Query against the Cloudflare GraphQL schema

A typical query against the Cloudflare GraphQL schema is made up of five components:

  • query - The root node.
  • viewer - A nested node indicating to GraphQL that you want to view the results. The viewer component represents the initial node of the user running the query.
  • zones or account - A nested node indicating the domain area or account you want to query against. The viewer can access one or more zones or accounts. Each zone or account contains a collection of datasets.
  • Leaf node - This specifies the dataset you want to query against in a zone or account. firewallEventsAdaptive is an example of a leaf node that represents a dataset for firewall events in a zone node.
  • Field - The fields in a query specify the set of metrics that you want to fetch. The firewallEventsAdaptive leaf node includes the clientIP field. If your leaf node queries requests, possible fields would include response bytes or the time at which requests were received.

The following example shows the format for a firewall query:

query{
  viewer {
      zones(filter: {...}) {
         firewallEventsAdaptive( limit: 10, orderBy: [...], filter: {...} ) {
           datetime, clientCountryName, action, ...
         }
      }
  }
}

​​ Example Query

The following query searches data from a zone for firewall events that occurred during a time interval. It sorts the results, limits the amount of results returned, and displays a set of fields for each firewall event.

Query Firewall events for a specific time interval
query
{
  viewer
  {
    zones(filter: { zoneTag: "11111111"})
    {
      firewallEventsAdaptive(
          filter: {
            datetime_gt: "2020-08-03T02:07:05Z",
            datetime_lt: "2020-08-03T17:07:05Z",
            requestSource: "eyeball" 
          },
          limit: 2,
          orderBy: [datetime_DESC, rayName_DESC])
      {
        action
        datetime
        rayName
        clientRequestHTTPHost
        userAgent
      }
    }
  }

}
  • zones(filter: { zoneTag: "11111111"}) confines the query to search to one zone.
  • firewallEventsAdaptive is the large dataset that you want to query against. The set of data returned is defined by the following:
    • filter:{} limits the scope to firewall events between two times: datetime_gt (greater than) and datetime_lt (less than). Adding the requestSource filter for eyeball returns data only about the end users of your website and excludes actions taken by Cloudflare products (for example, cache purge, healthchecks, Workers subrequests).
    • limit: 2 limits the results to 2 (the maximum value is 10,000).
    • orderBy sorts the results, first by datetime_DESC, the datetime field , in descending order, and then by the rayname, also in descending order.
    • The list of fields: action (Allow, Block, Challenge), datetime, rayName (the RayID), clientRequestHTTPHost (the host the client requested), and userAgent.

You can send the query with an API call or by clicking Play in the GraphiQL client. The format of the response is in JSON:

Query response from firewallEventsAdaptive
{
  "data": {
    "viewer": {
      "zones": [
        {
          "firewallEventsAdaptive": [
            {
              "action": "log",
              "clientRequestHTTPHost": "cloudflare.guru",
              "datetime": "2020-08-03T17:07:03Z",
              "rayName": "5bd1a1fc584357ed",
              "userAgent": "Mozilla/5.0 (compatible;Cloudflare-Healthchecks/1.0;+https://www.cloudflare.com/; healthcheck-id: 08c774cde2f3c385)"
            },
            {
              "action": "log",
              "clientRequestHTTPHost": "cloudflare.guru",
              "datetime": "2020-08-03T17:07:01Z",
              "rayName": "5bd1a1ef3bb5d296",
              "userAgent": "Mozilla/5.0 (compatible;Cloudflare-Healthchecks/1.0;+https://www.cloudflare.com/; healthcheck-id: 764497f790f6a070)"
            }
          ]
        }
      ]
    }
  },
  "errors": null

}

​​ Query two datasets in a single API call

This example query employs a broad range of GraphQL functionality. The example queries two datasets for the specified zone simultaneously, applies filters and aggregations, and sets a limit on the number of records returned. Note that you must include the limit argument, which can be equal or up to 10,000.

Query two datasets simultaneously
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
        }
      }
    }
  }

}

​​ Introspection

The GraphQL API offers introspection, which allows you to explore the graph (by making API calls) to see the available datasets, fields, and operations you can perform.

For an introduction to browsing the Analytics GraphQL API, refer to Explore the Analytics schema with GraphiQL.

​​ Helpful Resources

Here are some helpful articles about working with the Cloudflare Analytics API and GraphQL.

​​ Cloudflare specific

​​ General info on the GraphQL framework