Many clients might need help usingthe semantics of GraphQL and exploringthe possibilities of Cloudflare GraphQL API.

This page details how to use aGraphiQL client ↗ to compose and execute aGraphQL query.

You can find all details on how toconfigure a client here.

Click on the editing pane of GraphiQL and add this base query, replacingzone-id with your Cloudflare zone ID:

Note

To find the zone's tag, log in to your Cloudflare account and select the site forwhich you want to obtain the tag. In the Cloudflare dashboardOverview page,scroll to theAPI section in the right sidebar, which displays your zone andaccount tags.

To assist query building, the GraphiQL client has word completion. Insert yourcursor in the query, in this case on the line belowzones, and start enteringa value to engage the feature. For example, when you typefirewall, a popupmenu displays the datasets that return firewall information:

The text at the bottom of the list displays a short description of the data thatthe node returns.

Select the dataset you want to query and insert it. Either select the item in thelist, or scroll using arrow keys and press theReturn key.

Hover your mouse over a field to display a tooltip that describes the dataset.In this example, hovering over thefirewallEventsAdaptive node displays thisdescription:

To display information about the dataset, including required parameters, selectthe dataset name (blue text). TheDocumentation Explorer opens and displaysdetails about the dataset:

Note that thefilter andlimit arguments are required, as indicated by theexclamation mark (!) after their type definitions (gold text). In thisexample, theorderBy argument is not required, though when used it requires avalue of typeZoneFirewallEventsAdaptiveOrderBy.

To browse a list of supported filter fields, select the filter type definition(gold text) in the Documentation Explorer. In this example, the type isZoneFirewallEventsAdaptiveFilter_InputObject:

This example query shows the requiredfilter andlimit arguments forfirewallEventsAdaptive (as well as for the rest of GraphQL nodes):

To browse the fields you can use with your query, hover your cursor over thedataset name in your query, and in the tooltip that displays, select the datatype definition (gold text):

The Documentation Explorer opens and displays a list of fields:

To add the data fields that you want to read, type an opening brace ({) afterthe closing parenthesis for the parameters, then start typing the name of afield that you want to fetch. Use word completion to choose a field.

This example query returns theaction,datetime,clientRequestHTTPHost,anduserAgent fields:

Once you have entered all the fields you want to query, select thePlaybutton to submit the query. The response pane will contain the data fetched fromthe configured GraphQL API endpoint:

The GraphiQL client allows you to use placeholders for value and supply them viathevariables part of the payload.

Placeholder names should start with$ character, and you do not need to wrapplaceholders in quotes when you use them in the query.

Values for placeholders should be provided in JSON format, in which placeholdersare addressed without$ character. As an example, for a placeholder$zoneTagGraphQL API will read a value from thezoneTag field of supplied variablesobject.

To supply a value for a placeholder, select theQuery Variables pane and edita JSON object that defines your variables.

This example query uses thezoneTag query variable to represent the zone ID: