Cloudflare Docs
DNS
DNS
Visit DNS on GitHub
Set theme to dark (⇧+D)

Analytics API properties

This page describes API properties that you can use in API requests for DNS analytics.

​​ Metrics

A metric is a numerical value based on an attribute of the data, for example a query count.

In API requests, metrics are set in the metrics parameter. If you need to list multiple metrics, separate them with commas.

MetricNameExampleUnit
queryCountQuery count1000Count
uncachedCountUncached query count1Count
staleCountStale query count1Count
responseTimeAvgAverage response time1.0Time in milliseconds
responseTimeMedianMedian response time1.0Time in milliseconds
responseTime90th90th percentile response time1.0Time in milliseconds
responseTime99th99th percentile response time1.0Time in milliseconds

​​ Dimensions

Dimensions can be used to break down the data by given attributes.

In API requests, dimensions are set in the dimensions parameter. If you need to list multiple dimensions, separate them with commas.

DimensionNameExampleNotes
queryNameQuery Nameexample.com
queryTypeQuery TypeAAAATypes defined by IANA. Unknown types are empty.
responseCodeResponse CodeNOERRORResponse codes defined by IANA. Always uppercase.
responseCachedResponse CachedCachedEither Cached or Uncached.
coloNameColo NameSJCPoP code.
originOrigin2001:db8::1Origin used to resolve the query. Empty if N/A or if the query was answered from cache.
dayOfWeekDay Of Week1Break down by day of week. Monday is 1, and Sunday is 7.
tcpTCP1Either 1 or 0 depending on the protocol used.
ipVersionIP Version6IP protocol version used (currently 4 or 6).
querySizeBucketQuery Size Bucket16-31Query size bucket by multiples of 16.
responseSizeBucketResponse Size Bucket16-31Response size bucket by multiples of 16.

​​ Filters

Filters use the form dimension operator expression, where each part corresponds to the following:

  • Dimension: Specifies the dimension to filter on. For example, queryName.
  • Operator: Defines the type of filter match to use. Operators are specific to dimensions.
  • Expression: States the values to include or exclude from the results. Expressions use regular expression (regex) syntax.

​​ Filter operators

OperatorNameExampleDescriptionURL Encoded
==EqualsqueryName==example.comReturn results where queryName is exactly example.com.%3D%3D
!=Does not equalresponseCode!=NOERRORReturn results where responseCode is different from NOERROR.!%3D
>Greater thandimension>1000Return results where a dimension is greater than 1000.%3E
<Less thandimension<1000Return results where a dimension is less than 1000.%3C
>=Greater than or equal todimension>=1000Return results where a dimension is greater than or equal to 1000.%3E%3D
<=Less than or equal todimension<=1000Return results where a dimension is less than or equal to 1000.%3C%3D

​​ Combining filters

Combine filters using OR and AND boolean logic:

  • AND takes precedence over OR in all expressions.

  • The OR operator is defined using a comma , or the OR keyword surrounded by whitespace.

  • The AND operator is defined using a semicolon ; or the AND keyword surrounded by whitespace.

Examples using OR
  • responseCode==NOERROR,responseCode==NXDOMAIN indicates that response code is either NOERROR or NXDOMAIN.
  • coloName==SJC OR coloName==LAX indicates queries in either SJC or LAX.
Examples using AND
  • responseCode==NOERROR;queryType==AAAA indicates that response code is NOERROR and query type is AAAA.
  • queryType==AAAA AND coloName==SJC indicates AAAA queries in SJC.