Skip to content
Cloudflare API
Start here
API Reference
DNS Firewall
Analytics
Reports
Bytimes

By Time

client.dnsFirewall.analytics.reports.bytimes.get(stringdnsFirewallId, BytimeGetParams { account_id, dimensions, filters, 6 more } params, RequestOptionsoptions?): ByTime { data, data_lag, max, 5 more }
GET/accounts/{account_id}/dns_firewall/{dns_firewall_id}/dns_analytics/report/bytime

Retrieves a list of aggregate metrics grouped by time interval.

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)
DNS Firewall WriteDNS Firewall Read
ParametersExpand Collapse
dnsFirewallId: string

Identifier.

maxLength32
params: BytimeGetParams { account_id, dimensions, filters, 6 more }
account_id: string

Path param: Identifier.

maxLength32
dimensions?: string

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

filters?: string

Query param: Segmentation filter in ‘attribute operator value’ format.

limit?: number

Query param: Limit number of returned metrics.

metrics?: string

Query param: A comma-separated list of metrics to query.

since?: string

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

formatdate-time
sort?: string

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

time_delta?: "all" | "auto" | "year" | 7 more

Query param: Unit of time to group data by.

One of the following:
"all"
"auto"
"year"
"quarter"
"month"
"week"
"day"
"hour"
"dekaminute"
"minute"
until?: string

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

formatdate-time
ReturnsExpand Collapse
ByTime { data, data_lag, max, 5 more }
data: Array<Data>

Array with one row per combination of dimension values.

dimensions: Array<string>

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

metrics: Array<Array<number>>

Array with one item per requested metric. Each item is an array of values, broken down by time interval.

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: Query { dimensions, limit, metrics, 5 more }
dimensions: Array<string>

Array of dimension names.

limit: number

Limit number of returned metrics.

metrics: Array<string>

Array of metric names.

since: string

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

formatdate-time
time_delta: "all" | "auto" | "year" | 7 more

Unit of time to group data by.

One of the following:
"all"
"auto"
"year"
"quarter"
"month"
"week"
"day"
"hour"
"dekaminute"
"minute"
until: string

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

formatdate-time
filters?: string

Segmentation filter in ‘attribute operator value’ format.

sort?: Array<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
time_intervals: Array<Array<string>>

Array of time intervals in the response data. Each interval is represented as an array containing two values: the start time, and the end time.

totals: unknown

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

By Time

import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted
});

const byTime = await client.dnsFirewall.analytics.reports.bytimes.get(
  '023e105f4ecef8ad9ca31a8372d0c353',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
);

console.log(byTime.data);
{
  "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",
      "time_delta": "hour",
      "until": "2023-11-11T13:00:00Z",
      "filters": "responseCode==NOERROR,queryType==A",
      "sort": [
        "+responseCode",
        "-queryName"
      ]
    },
    "rows": 100,
    "time_intervals": [
      [
        "2023-11-11T12:00:00Z"
      ]
    ],
    "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",
      "time_delta": "hour",
      "until": "2023-11-11T13:00:00Z",
      "filters": "responseCode==NOERROR,queryType==A",
      "sort": [
        "+responseCode",
        "-queryName"
      ]
    },
    "rows": 100,
    "time_intervals": [
      [
        "2023-11-11T12:00:00Z"
      ]
    ],
    "totals": {}
  }
}