Table

GET/zones/{zone_id}/dns_analytics/report

Retrieves a list of summarised aggregate metrics over a given time period.

See Analytics API properties for detailed information about the available query parameters.

Security

API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY

API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194

Accepted Permissions (at least one required)

Analytics Read

Path ParametersExpand Collapse

zone_id: string

Identifier.

maxLength32

Query ParametersExpand Collapse

dimensions: optional string

A comma-separated list of dimensions to group results by.

filters: optional string

Segmentation filter in 'attribute operator value' format.

limit: optional number

Limit number of returned metrics.

metrics: optional string

A comma-separated list of metrics to query.

since: optional string

Start date and time of requesting data period in ISO 8601 format.

formatdate-time

sort: optional string

A comma-separated list of dimensions to sort by, where each dimension may be prefixed by - (descending) or + (ascending).

until: optional string

End date and time of requesting data period in ISO 8601 format.

formatdate-time

ReturnsExpand Collapse

errors: array of object { code, message, documentation_url, source }

code: number

minimum1000

message: string

documentation_url: optional string

source: optional object { pointer }

pointer: optional string

messages: array of object { code, message, documentation_url, source }

code: number

minimum1000

message: string

documentation_url: optional string

source: optional object { pointer }

pointer: optional string

success: true

Whether the API call was successful.

result: optional Report { data, data_lag, max, 4 more }

data: array of object { dimensions, metrics }

Array with one row per combination of dimension values.

dimensions: array of string

Array of dimension values, representing the combination of dimension values corresponding to this row.

metrics: array of number

Array with one item per requested metric. Each item is a single value.

data_lag: number

Number of seconds between current time and last processed event, in another words how many seconds of data could be missing.

minimum0

max: unknown

Maximum results for each metric (object mapping metric names to values). Currently always an empty object.

min: unknown

Minimum results for each metric (object mapping metric names to values). Currently always an empty object.

query: object { dimensions, limit, metrics, 4 more }

dimensions: array of string

Array of dimension names.

limit: number

Limit number of returned metrics.

metrics: array of string

Array of metric names.

since: string

Start date and time of requesting data period in ISO 8601 format.

formatdate-time

until: string

End date and time of requesting data period in ISO 8601 format.

formatdate-time

filters: optional string

Segmentation filter in 'attribute operator value' format.

sort: optional array of string

Array of dimensions to sort by, where each dimension may be prefixed by - (descending) or + (ascending).

rows: number

Total number of rows in the result.

minimum0

totals: unknown

Total results for metrics across all data (object mapping metric names to values).

Table

curl https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_analytics/report \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "data": [
      {
        "dimensions": [
          "NODATA"
        ],
        "metrics": [
          0
        ]
      }
    ],
    "data_lag": 60,
    "max": {},
    "min": {},
    "query": {
      "dimensions": [
        "responseCode",
        "queryName"
      ],
      "limit": 100,
      "metrics": [
        "queryCount",
        "responseTimeAvg"
      ],
      "since": "2023-11-11T12:00:00Z",
      "until": "2023-11-11T13:00:00Z",
      "filters": "responseCode==NOERROR,queryType==A",
      "sort": [
        "+responseCode",
        "-queryName"
      ]
    },
    "rows": 100,
    "totals": {}
  }
}

Returns Examples

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "data": [
      {
        "dimensions": [
          "NODATA"
        ],
        "metrics": [
          0
        ]
      }
    ],
    "data_lag": 60,
    "max": {},
    "min": {},
    "query": {
      "dimensions": [
        "responseCode",
        "queryName"
      ],
      "limit": 100,
      "metrics": [
        "queryCount",
        "responseTimeAvg"
      ],
      "since": "2023-11-11T12:00:00Z",
      "until": "2023-11-11T13:00:00Z",
      "filters": "responseCode==NOERROR,queryType==A",
      "sort": [
        "+responseCode",
        "-queryName"
      ]
    },
    "rows": 100,
    "totals": {}
  }
}