Version 2.4.7.20261116085428 · latest

Reports reports

Real-time curves, rankings and usage for sites and TCP/UDP forwarding, node monitoring curves and rankings, unconfigured-domain Top, temporary whitelist and access logs; tenants see only their own data.

Pick an endpoint to see its example call on the right.

Authentication: User (some parameters admin only)43 endpoints

Authentication

Send the X-API-Key header (create a key on the API Keys page; the key is shown only once at creation). An Authorization: Bearer token obtained by logging in also works.

X-API-Key

Authentication failures return 401; forbidden returns 403 (code such as insufficient_scope).

Conventions

Paging uses page (from 1) and page_size; sort with sort=field or sort=-field.

Times are RFC 3339 (UTC); amounts are in cents.

Writes return 200/201/204 on success; duplicates of a unique key return 409.

GET/api/v2/reports/access-log-exportsList access log download requests

Authentication: User

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
POST/api/v2/reports/access-log-exportsRequest an access log download

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
startRequiredstring Start time (inclusive), RFC 3339
endRequiredstring End time (exclusive), RFC 3339
site_idsstring Only these sites: comma-separated positive integers, at most 200 after deduplication (more returns 422); for more than 200 sites send a filter (group_id / upid / tenant_ids) instead. Intersected with group_id, upid and tenant_ids; sites a tenant cannot see have no data.
group_idinteger Only sites in this site group (expanded to a site set on the server and intersected with the other scope filters; a tenant only expands its own sites).
upidinteger Only sites under this user package.
tenant_idsstring Admin only: only these tenants, comma-separated positive integers, at most 200 after deduplication (more returns 422); tenant credentials sending it get 403.
hoststring Exact match on request Host (case-insensitive).
server_portinteger Filter by access port.
ipstring Exact match on client address.
uristring Filter by request URI prefix (must start with /).
refererstring Exact, case-sensitive match on the Referer request header; an empty value (referer=) selects direct visits that sent no Referer.
http_verstring Filter by HTTP protocol version (same spelling as http_ver in the response).
Values ["1.0","1.1","2","3"]
methodstring Filter by request method (upper case, such as GET or POST).
statusinteger Filter by status code.
node_idinteger Filter by node.
cache_statusstring Filter by cache status.
Values ["NONE","HIT","MISS","EXPIRED","STALE","UPDATING","REVALIDATED","BYPASS"]
countrystring Filter by client country (ISO 3166-1 alpha-2, e.g. CN).
provstring Filter by client province (first two digits of GB/T 2260, e.g. 44).
ispstring Filter by client ISP (telecom, unicom, mobile, cbn, edu, cloud, other).
blockedboolean true = only blocked requests (action = block).
block_reasonstring Filter by block reason, same meaning as block_reason on a log row: region = blocked by region limit, region_log = region limit log-only hit (not blocked), acl = blocked by ACL, other = blocked by other protection.
Values ["region","region_log","acl","other"]
status_classstring Filter by status class: 1xx / 2xx / 3xx / 4xx / 5xx; error = failed requests (status ≥ 400 and not a blocked request). Intersected with status when both are given.
Values ["1xx","2xx","3xx","4xx","5xx","error"]
slow_msinteger Only slow requests, i.e. request time (request_time_ms) greater than this many milliseconds.
cache_status_notstring Exclude this cache status (negation of cache_status); the miss count in facets equals cache_status_not=HIT. Intersected with cache_status when both are given.
Values ["NONE","HIT","MISS","EXPIRED","STALE","UPDATING","REVALIDATED","BYPASS"]
qstring Search, intersected with the other filters. By default (q_match=prefix): a whole IP matches client IP exactly (uses the client_ip skip index); otherwise a hit on any of status code (exactly three digits matches the status; 1xx to 5xx matches the class), URL prefix or host prefix (case-insensitive, equality included) counts. With q_match=contains the old substring semantics apply: status as above, client IP / URL / host (case-insensitive) containing the text, which no index can serve.
q_matchstring How q matches: prefix (default) = IP equality, URL / host prefix; contains = substring match (slow, scans the whole time window). Ignored without q.
Values ["prefix","contains"]
GET/api/v2/reports/access-logsList access logs

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
sortstring Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id`
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
startRequiredstring Start time (inclusive), RFC 3339
endRequiredstring End time (exclusive), RFC 3339
cursorstring Time cursor; pass back next_cursor of the previous page (same sort and filters). page is ignored when set.
site_idsstring Only these sites: comma-separated positive integers, at most 200 after deduplication (more returns 422); for more than 200 sites send a filter (group_id / upid / tenant_ids) instead. Intersected with group_id, upid and tenant_ids; sites a tenant cannot see have no data.
group_idinteger Only sites in this site group (expanded to a site set on the server and intersected with the other scope filters; a tenant only expands its own sites).
upidinteger Only sites under this user package.
tenant_idsstring Admin only: only these tenants, comma-separated positive integers, at most 200 after deduplication (more returns 422); tenant credentials sending it get 403.
hoststring Exact match on request Host (case-insensitive).
server_portinteger Filter by access port.
ipstring Exact match on client address.
uristring Filter by request URI prefix (must start with /).
refererstring Exact, case-sensitive match on the Referer request header; an empty value (referer=) selects direct visits that sent no Referer.
http_verstring Filter by HTTP protocol version (same spelling as http_ver in the response).
Values ["1.0","1.1","2","3"]
methodstring Filter by request method (upper case, such as GET or POST).
statusinteger Filter by status code.
node_idinteger Filter by node.
cache_statusstring Filter by cache status.
Values ["NONE","HIT","MISS","EXPIRED","STALE","UPDATING","REVALIDATED","BYPASS"]
countrystring Filter by client country (ISO 3166-1 alpha-2, e.g. CN).
provstring Filter by client province (first two digits of GB/T 2260, e.g. 44).
ispstring Filter by client ISP (telecom, unicom, mobile, cbn, edu, cloud, other).
blockedboolean true = only blocked requests (action = block).
block_reasonstring Filter by block reason, same meaning as block_reason on a log row: region = blocked by region limit, region_log = region limit log-only hit (not blocked), acl = blocked by ACL, other = blocked by other protection.
Values ["region","region_log","acl","other"]
status_classstring Filter by status class: 1xx / 2xx / 3xx / 4xx / 5xx; error = failed requests (status ≥ 400 and not a blocked request). Intersected with status when both are given.
Values ["1xx","2xx","3xx","4xx","5xx","error"]
slow_msinteger Only slow requests, i.e. request time (request_time_ms) greater than this many milliseconds.
cache_status_notstring Exclude this cache status (negation of cache_status); the miss count in facets equals cache_status_not=HIT. Intersected with cache_status when both are given.
Values ["NONE","HIT","MISS","EXPIRED","STALE","UPDATING","REVALIDATED","BYPASS"]
qstring Search, intersected with the other filters. By default (q_match=prefix): a whole IP matches client IP exactly (uses the client_ip skip index); otherwise a hit on any of status code (exactly three digits matches the status; 1xx to 5xx matches the class), URL prefix or host prefix (case-insensitive, equality included) counts. With q_match=contains the old substring semantics apply: status as above, client IP / URL / host (case-insensitive) containing the text, which no index can serve.
q_matchstring How q matches: prefix (default) = IP equality, URL / host prefix; contains = substring match (slow, scans the whole time window). Ignored without q.
Values ["prefix","contains"]
facetsboolean true / 1 = include facets (counts for each quick filter) in the response. Counted under all filters except the quick ones (status_class, slow_ms, cache_status_not, blocked, block_reason), so they do not move with the quick filter.
totalboolean false / 0 = skip counting the total (the response omits total, saving one full count); defaults to true.
GET/api/v2/reports/checkupSite checkup overview

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
qstring Search by site name or domain (substring match).
sortstring Sort: score ascending (worst first, default) or name.
Values ["score","name"]
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
cursorstring Page cursor; pass back next_cursor of the previous page (same sort and filters) to read on from that row without slowing down on deep pages. page is ignored when set; a cursor that does not match sort is a 400.
GET/api/v2/reports/checkup/historyCheckup score history

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
site_idinteger Filter by site.
GET/api/v2/reports/checkup/ignoresCheckup ignores

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
site_idinteger Filter by site.
POST/api/v2/reports/checkup/ignores/batchAdd or remove checkup ignores in bulk

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
keysRequiredstring[] Check keys.
opRequiredstring add puts keys on the ignore list (existing ones are untouched); remove takes them off.
Values ["add","remove"]
site_idsRequiredinteger[] Sites to process, at most 500.
GET/api/v2/reports/checkup/issuesCheckup problems grouped by check

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
qstring Search by site name or domain (substring match); only matching sites are counted.
GET/api/v2/reports/checkup/issues/{key}/sitesSites affected by a checkup problem

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
qstring Search by site name or domain (substring match).
sortstring Sort order: score is lowest checkup score first (default); attacks is most attacks in the last 7 days first (WAF and default-CC problems carry the count, other checks count as 0; ties fall back to score).
Values ["score","attacks"]
typestring rec_type only - filter by site type; undecided lists sites whose type could not be determined (the checkup only noted them and did not count them as problems; this is the only place they are listed). 422 when key is not rec_type.
Values ["corporate","shop","content","api","admin","download","undecided"]
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
cursorstring Page cursor; pass back next_cursor of the previous page (same sort and filters) to read on from that row without slowing down on deep pages. page is ignored when set; a cursor that does not match sort is a 400.
POST/api/v2/reports/checkup/recheckRun the checkup again

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
site_idsinteger[] Sites to process, at most 500.
GET/api/v2/reports/checkup/runs/activeThe checkup batch in progress

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
GET/api/v2/reports/checkup/runs/{id}Checkup batch progress

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
site_idsinteger[] Ids of the sites to report completion for (the panel's current page); repeatable, at most 200; omit and done_site_ids is an empty array.
GET/api/v2/reports/checkup/settingsGet checkup settings

Authentication: User (some parameters admin only)

PUT/api/v2/reports/checkup/settingsSave checkup settings

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
frequencyRequiredstring Frequency: daily at 03:00, weekly on Monday at 03:00, or manual only.
Values ["daily","weekly","manual"]
ignore_keysstring[] Check keys ignored for all sites (including sites added later), combined with per-site ignores. GET always returns it (empty array when none). Omit it on PUT to leave it unchanged; an empty array clears all; an unknown key returns 422. When set by an administrator it is platform-wide and applies to the sites of every tenant.
notify_criticalRequiredboolean Raise an alert when a critical problem appears (uses the channels in alert settings).
GET/api/v2/reports/checkup/sites/{id}Site checkup report

Authentication: User (some parameters admin only)

PUT/api/v2/reports/checkup/sites/{id}/appOverride a site's detected application

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
namestring Site name.
resetboolean true clears the override and returns to automatic detection (name and version are ignored).
versionstring Application version; may be left empty.
PUT/api/v2/reports/checkup/sites/{id}/ignoresSet a site's checkup ignores

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
keysRequiredstring[] Check keys.
GET/api/v2/reports/host-not-found/topUnconfigured domain Top

Authentication: Admin only

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
startRequiredstring Start time (inclusive), RFC 3339
endRequiredstring End time (exclusive), RFC 3339
node_idinteger Only entries reported by this node.
domainstring Filter by host substring (case-insensitive, literal match).
kindHostNotFoundKind Only this kind (kinds are judged by the master, not stored; the top 500 domains by count are judged and filtered before paging, total counts the filtered rows).
Values ["site","pointed_here","not_pointed","typo","scanner","unknown"]
orderstring Sort direction by count, default desc.
Values ["desc","asc"]
GET/api/v2/reports/ip-seenFirst and last time a visitor IP was seen

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
site_idsstring Only these sites: comma-separated positive integers, at most 200 after deduplication (more returns 422); for more than 200 sites send a filter (group_id / upid / tenant_ids) instead. Intersected with group_id, upid and tenant_ids; sites a tenant cannot see have no data.
group_idinteger Only sites in this site group (expanded to a site set on the server and intersected with the other scope filters; a tenant only expands its own sites).
upidinteger Only sites under this user package.
tenant_idsstring Admin only: only these tenants, comma-separated positive integers, at most 200 after deduplication (more returns 422); tenant credentials sending it get 403.
ipRequiredstring Client address to look up (IPv4 or IPv6).
startstring Window start (inclusive), RFC 3339; must come with end (only one of them gives 422); without both the whole access log retention is used. The part before the retention is clipped (the window may be longer than the retention).
endstring Window end (exclusive), RFC 3339; must come with start (only one of them gives 422).
GET/api/v2/reports/nodes/realtimeNode real-time curves

Authentication: Admin only

Query parameters

FieldTypeDescription
startRequiredstring Start time (inclusive), RFC 3339
endRequiredstring End time (exclusive), RFC 3339
node_idRequiredinteger Node. A sub-IP id returns the curves of the main node it belongs to (metrics are collected per main node).
metricRequiredstring Node metric (same as node_metrics.metric). tls_hs_reject is the number of TLS handshakes rejected by handshake-flood protection; worker_drain_killed is the number of draining old nginx workers force-terminated (SIGTERM); shm_used_pct is the nginx shared-zone used percentage (label = zone name; the three control zones always, other zones only at 50% used or more); shm_write_fail is the number of shared-zone writes that found no memory (label = zone name; only reported when new).
Values ["nic_in_bps","nic_out_bps","cpu_pct","mem_pct","load1","disk_space_pct","disk_inode_pct","tcp_conn","nginx_active","nginx_reading","nginx_writing","nginx_waiting","log_dropped","tls_hs_reject","worker_drain_killed","shm_used_pct","shm_write_fail"]
intervalstring Bucket width; chosen automatically from the time span by default.
Values ["1m","2m","5m","10m","30m","1h"]
GET/api/v2/reports/nodes/realtime-batchNode real-time curves (several metrics in one call)

Authentication: Admin only

Query parameters

FieldTypeDescription
startRequiredstring Start time (inclusive), RFC 3339
endRequiredstring End time (exclusive), RFC 3339
node_idRequiredinteger Node. A sub-IP id returns the curves of the main node it belongs to (metrics are collected per main node).
metricsRequiredstring Node metrics, comma-separated.
intervalstring Bucket width; chosen automatically from the time span by default.
Values ["1m","2m","5m","10m","30m","1h"]
GET/api/v2/reports/nodes/summaryNode ranking table

Authentication: Admin only

Query parameters

FieldTypeDescription
windowinteger Averaging window in minutes; 5 by default.
Values [1,5,30,60]
GET/api/v2/reports/nodes/topNode ranking

Authentication: Admin only

Query parameters

FieldTypeDescription
startRequiredstring Start time (inclusive), RFC 3339
endRequiredstring End time (exclusive), RFC 3339
metricRequiredstring Node metric (same as node_metrics.metric). tls_hs_reject is the number of TLS handshakes rejected by handshake-flood protection; worker_drain_killed is the number of draining old nginx workers force-terminated (SIGTERM); shm_used_pct is the nginx shared-zone used percentage (label = zone name; the three control zones always, other zones only at 50% used or more); shm_write_fail is the number of shared-zone writes that found no memory (label = zone name; only reported when new).
Values ["nic_in_bps","nic_out_bps","cpu_pct","mem_pct","load1","disk_space_pct","disk_inode_pct","tcp_conn","nginx_active","nginx_reading","nginx_writing","nginx_waiting","log_dropped","tls_hs_reject","worker_drain_killed","shm_used_pct","shm_write_fail"]
GET/api/v2/reports/security/overviewSecurity overview

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
startRequiredstring Start time (inclusive), RFC 3339
endRequiredstring End time (exclusive), RFC 3339
site_idinteger Filter by site.
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
GET/api/v2/reports/sites/geoVisitor location statistics

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
startRequiredstring Start time (inclusive), RFC 3339
endRequiredstring End time (exclusive), RFC 3339
site_idsstring Only these sites: comma-separated positive integers, at most 200 after deduplication (more returns 422); for more than 200 sites send a filter (group_id / upid / tenant_ids) instead. Intersected with group_id, upid and tenant_ids; sites a tenant cannot see have no data.
group_idinteger Only sites in this site group (expanded to a site set on the server and intersected with the other scope filters; a tenant only expands its own sites).
upidinteger Only sites under this user package.
tenant_idsstring Admin only: only these tenants, comma-separated positive integers, at most 200 after deduplication (more returns 422); tenant credentials sending it get 403.
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
ipstring Exact match on client address.
GET/api/v2/reports/sites/overviewSite traffic overview

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
startRequiredstring Start time (inclusive), RFC 3339
endRequiredstring End time (exclusive), RFC 3339
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
site_idsstring Only these sites: comma-separated positive integers, at most 200 after deduplication (more returns 422); for more than 200 sites send a filter (group_id / upid / tenant_ids) instead. Intersected with group_id, upid and tenant_ids; sites a tenant cannot see have no data.
group_idinteger Only sites in this site group (expanded to a site set on the server and intersected with the other scope filters; a tenant only expands its own sites).
upidinteger Only sites under this user package.
tenant_idsstring Admin only: only these tenants, comma-separated positive integers, at most 200 after deduplication (more returns 422); tenant credentials sending it get 403.
intervalstring Bucket width; chosen automatically from the time span by default.
Values ["1m","2m","5m","10m","30m","1h"]
include_noconfigboolean Admin only: also include unconfigured traffic (site_id = 0).
comparestring prev = also return the previous period of the same length (the compare field); omitted by default.
Values ["prev"]
GET/api/v2/reports/sites/protocol-configSite protocol configuration distribution

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
GET/api/v2/reports/sites/realtimeSite real-time curves

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
startRequiredstring Start time (inclusive), RFC 3339
endRequiredstring End time (exclusive), RFC 3339
site_idsstring Only these sites: comma-separated positive integers, at most 200 after deduplication (more returns 422); for more than 200 sites send a filter (group_id / upid / tenant_ids) instead. Intersected with group_id, upid and tenant_ids; sites a tenant cannot see have no data.
group_idinteger Only sites in this site group (expanded to a site set on the server and intersected with the other scope filters; a tenant only expands its own sites).
upidinteger Only sites under this user package.
tenant_idsstring Admin only: only these tenants, comma-separated positive integers, at most 200 after deduplication (more returns 422); tenant credentials sending it get 403.
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
metricRequiredstring Metric.
Values ["bandwidth","bandwidth_in","traffic","traffic_in","backend_bandwidth","backend_traffic","req","qps","req_hit_ratio","byte_hit_ratio","status_4xx","status_5xx","backend_resp_time","backend_timeout","blocked","challenged"]
intervalstring Bucket width; chosen automatically from the time span by default.
Values ["1m","2m","5m","10m","30m","1h"]
include_noconfigboolean Admin only: when no site scope (site_ids / group_id) is given, also include unconfigured traffic (site_id = 0).
GET/api/v2/reports/sites/realtime-batchSite real-time curves (several metrics in one call)

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
startRequiredstring Start time (inclusive), RFC 3339
endRequiredstring End time (exclusive), RFC 3339
site_idsstring Only these sites: comma-separated positive integers, at most 200 after deduplication (more returns 422); for more than 200 sites send a filter (group_id / upid / tenant_ids) instead. Intersected with group_id, upid and tenant_ids; sites a tenant cannot see have no data.
group_idinteger Only sites in this site group (expanded to a site set on the server and intersected with the other scope filters; a tenant only expands its own sites).
upidinteger Only sites under this user package.
tenant_idsstring Admin only: only these tenants, comma-separated positive integers, at most 200 after deduplication (more returns 422); tenant credentials sending it get 403.
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
metricsRequiredstring Metrics, comma-separated.
intervalstring Bucket width; chosen automatically from the time span by default.
Values ["1m","2m","5m","10m","30m","1h"]
include_noconfigboolean Admin only: when no site scope (site_ids / group_id) is given, also include unconfigured traffic (site_id = 0).
GET/api/v2/reports/sites/topSite ranking

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
startRequiredstring Start time (inclusive), RFC 3339
endRequiredstring End time (exclusive), RFC 3339
site_idsstring Only these sites: comma-separated positive integers, at most 200 after deduplication (more returns 422); for more than 200 sites send a filter (group_id / upid / tenant_ids) instead. Intersected with group_id, upid and tenant_ids; sites a tenant cannot see have no data.
group_idinteger Only sites in this site group (expanded to a site set on the server and intersected with the other scope filters; a tenant only expands its own sites).
upidinteger Only sites under this user package.
tenant_idsstring Admin only: only these tenants, comma-separated positive integers, at most 200 after deduplication (more returns 422); tenant credentials sending it get 403.
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
dimstring Ranking dimension; use either dim or dims.
Values ["ip","prefix","url","referer","site","status","http_ver","scheme","cache_status","ctype","country","prov","isp","port","block_reason"]
dimsstring Fetch the top limit rows of several dimensions at once, comma-separated dimension names (values as for dim, at most 12); use either dim or dims.
limitinteger Rows per dimension; defaults to and capped by the reports.top_size system setting.
metricstring Which item to sort by and use as value, default count; the server returns the global top N ordered by it (not a re-sort of fetched rows).
Values ["count","bytes","blocked","origin"]
actionstring Only count requests with this action (pass = allowed, challenge = challenged, block = blocked).
Values ["pass","challenge","block"]
server_portinteger Only count requests to this listening port; not supported for the prefix dimension (422).
briefboolean Overview mode: rows carry only count / bytes (region rankings still carry geo_summary); origin_bytes, blocked, main_reason and IP location are omitted, and a country ranking by request count reads the per-minute summary instead of the access log. Defaults to false.
GET/api/v2/reports/streams/realtimeTCP/UDP forwarding real-time curves

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
startRequiredstring Start time (inclusive), RFC 3339
endRequiredstring End time (exclusive), RFC 3339
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
portinteger Filter by stream listen port.
metricRequiredstring Metric.
Values ["bandwidth","bandwidth_in","traffic","traffic_in","req","conn_peak"]
intervalstring Bucket width; chosen automatically from the time span by default.
Values ["1m","2m","5m","10m","30m","1h"]
GET/api/v2/reports/streams/topTCP/UDP forwarding ranking

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
startRequiredstring Start time (inclusive), RFC 3339
endRequiredstring End time (exclusive), RFC 3339
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
dimstring Ranking dimension, default port.
Values ["port","ip"]
portsstring Only these listen ports: comma-separated integers between 1 and 65535, at most 200 after deduplication (more, or a malformed value, returns 422); omit for all ports. Applies to both dimensions, so a selected port outside the top N is still listed.
metricstring Which item to sort by and use as value, default count; the server returns the global top N ordered by it (not a re-sort of fetched rows).
Values ["count","bytes","blocked","origin"]
GET/api/v2/reports/tmp-whitelistList node temporary whitelist records

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
site_idinteger Filter by site.
ipstring Exact match on client address (IPv6 as /64 prefix address).
activeboolean true = only entries not yet expired.
GET/api/v2/reports/usageUsage curves

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
startRequiredstring Start time (inclusive), RFC 3339
endRequiredstring End time (exclusive), RFC 3339
site_idsstring Only these sites: comma-separated positive integers, at most 200 after deduplication (more returns 422); for more than 200 sites send a filter (group_id / upid / tenant_ids) instead. Intersected with group_id, upid and tenant_ids; sites a tenant cannot see have no data.
group_idinteger Only sites in this site group (expanded to a site set on the server and intersected with the other scope filters; a tenant only expands its own sites).
upidinteger Only sites under this user package.
tenant_idsstring Admin only: only these tenants, comma-separated positive integers, at most 200 after deduplication (more returns 422); tenant credentials sending it get 403.
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
kindstring site (default) = sites; stream = TCP/UDP forwarding.
Values ["site","stream"]
metricRequiredstring Metric.
Values ["bandwidth","traffic","req","qps","req_hit_ratio","status_5xx_ratio","status_4xx_ratio","backend_bandwidth","backend_traffic","backend_resp_time","blocked"]
intervalstring auto (default), 5m or 1h.
Values ["auto","5m","1h"]
portinteger Filter by stream listen port.
include_noconfigboolean Admin only: when no site scope (site_ids / group_id) is given, also include unconfigured traffic (site_id = 0).
GET/api/v2/reports/waf-eventsList WAF events

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
tenant_idsstring Admin only: only these tenants, comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); a single ID works too. Filters only and does not switch the request scope; combined with tenant_id and other filters as an intersection. A tenant credential sending a non-empty value gets 403
startstring Start time (inclusive), RFC 3339; no lower bound when omitted (events are kept for 7 days).
endstring End time (exclusive), RFC 3339; no upper bound when omitted.
site_idinteger Filter by site.
site_idsstring Filter by sites: comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); a single ID works too; combined with other filters as an intersection
ipstring Filter by client address: a single IPv4/IPv6 address matches exactly; a CIDR range (IPv4-mapped notation accepted) matches by address interval. Prefixes shorter than /8 (IPv4) or /32 (IPv6) are rejected with 422.
urlstring URL contains (case-sensitive substring of the masked path and query string).
ja4string Exact match on the client TLS fingerprint JA4 (events without a fingerprint never match).
rule_idinteger Filter by the matched rule id.
actionstring Filter by action: block, log, challenge, mask or replace.
Values ["block","log","challenge","mask","replace"]
typestring[] Filter by event type; repeat to select several, omit for all.
countrystring Filter by country name as recorded by the node geo database (exact match).
provincestring Filter by province (exact match).
node_idinteger Filter by reporting node; tenants cannot see node ids, so the parameter is ignored for them (no error).
node_idsstring Filter by reporting nodes: comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); combined with node_id as an intersection. Tenants cannot see node ids, so the parameter is ignored for them (no error).
observeboolean true = only events recorded in observe mode; false or omitted = no such filter.
blockedboolean true = only blocks in block mode (action = block, not observe); false = only the rest.
dispositionstring other = only events outside blocked / challenge / observe-only (not observe mode and action is neither block nor challenge, i.e. log, mask, replace); omitted = no such filter.
Values ["other"]
GET/api/v2/reports/waf-events/exportExport WAF events as CSV

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
tenant_idsstring Admin only: only these tenants, comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); a single ID works too. Filters only and does not switch the request scope; combined with tenant_id and other filters as an intersection. A tenant credential sending a non-empty value gets 403
startstring Start time (inclusive), RFC 3339; no lower bound when omitted (events are kept for 7 days).
endstring End time (exclusive), RFC 3339; no upper bound when omitted.
site_idinteger Filter by site.
site_idsstring Filter by sites: comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); a single ID works too; combined with other filters as an intersection
ipstring Filter by client address: a single IPv4/IPv6 address matches exactly; a CIDR range (IPv4-mapped notation accepted) matches by address interval. Prefixes shorter than /8 (IPv4) or /32 (IPv6) are rejected with 422.
urlstring URL contains (case-sensitive substring of the masked path and query string).
ja4string Exact match on the client TLS fingerprint JA4 (events without a fingerprint never match).
rule_idinteger Filter by the matched rule id.
actionstring Filter by action: block, log, challenge, mask or replace.
Values ["block","log","challenge","mask","replace"]
typestring[] Filter by event type; repeat to select several, omit for all.
countrystring Filter by country name as recorded by the node geo database (exact match).
provincestring Filter by province (exact match).
node_idinteger Filter by reporting node; tenants cannot see node ids, so the parameter is ignored for them (no error).
node_idsstring Filter by reporting nodes: comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); combined with node_id as an intersection. Tenants cannot see node ids, so the parameter is ignored for them (no error).
observeboolean true = only events recorded in observe mode; false or omitted = no such filter.
blockedboolean true = only blocks in block mode (action = block, not observe); false = only the rest.
dispositionstring other = only events outside blocked / challenge / observe-only (not observe mode and action is neither block nor challenge, i.e. log, mask, replace); omitted = no such filter.
Values ["other"]
GET/api/v2/reports/waf-events/summarySummarize WAF events

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
tenant_idsstring Admin only: only these tenants, comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); a single ID works too. Filters only and does not switch the request scope; combined with tenant_id and other filters as an intersection. A tenant credential sending a non-empty value gets 403
startRequiredstring Start of the time window (inclusive), RFC 3339.
endRequiredstring End of the time window (exclusive), RFC 3339; must be after start, at most 31 days apart.
site_idinteger Filter by site.
site_idsstring Filter by sites: comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); a single ID works too; combined with other filters as an intersection
ipstring Filter by client address: a single IPv4/IPv6 address matches exactly; a CIDR range (IPv4-mapped notation accepted) matches by address interval. Prefixes shorter than /8 (IPv4) or /32 (IPv6) are rejected with 422.
urlstring URL contains (case-sensitive substring of the masked path and query string).
ja4string Exact match on the client TLS fingerprint JA4 (events without a fingerprint never match).
rule_idinteger Filter by the matched rule id.
actionstring Filter by action: block, log, challenge, mask or replace.
Values ["block","log","challenge","mask","replace"]
typestring[] Filter by event type; repeat to select several, omit for all.
countrystring Filter by country name as recorded by the node geo database (exact match).
provincestring Filter by province (exact match).
node_idinteger Filter by reporting node; tenants cannot see node ids, so the parameter is ignored for them (no error).
node_idsstring Filter by reporting nodes: comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); combined with node_id as an intersection. Tenants cannot see node ids, so the parameter is ignored for them (no error).
observeboolean true = only events recorded in observe mode; false or omitted = no such filter.
blockedboolean true = only blocks in block mode (action = block, not observe); false = only the rest.
dispositionstring other = only events outside blocked / challenge / observe-only (not observe mode and action is neither block nor challenge, i.e. log, mask, replace); omitted = no such filter.
Values ["other"]
GET/api/v2/reports/waf-events/{event_id}Get a WAF event

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
POST/api/v2/reports/waf-events/{event_id}/allowAllow-list a WAF event

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data

Request body application/json

FieldTypeDescription
paramstring Name of the matched parameter, header or cookie; empty for unnamed locations.
pathstring Limit to this path prefix; must equal the event URL path or be a prefix ending in / (e.g. /api/); a bare / must be combined with a rule or parameter. Omit for any path.
ruleboolean Skip only the matched rule (rule_ids); not allowed for non-rule events (rule id 0) or semantic events.
Default false

Reports object

FieldTypeDescription
actionstring Protection action: pass, challenge or block.
adviceinteger Number of suggestions.
appstring Detected application; empty when none was recognised.
app_manualboolean The application was overridden by hand.
app_versionstring Application version; empty when it could not be read.
approxboolean The ranking comes from each node's per-minute top K (ip, prefix, url, referer); nodes report only their own top K, so totals are approximate. False when read from access logs (action or server_port given).
atstring Time it happened (the last hit inside the window).
attack_typesWafEventCount[] Attack type distribution (sqli, xss, scanner, rce, traversal, other and semantic, bot, upload, tamper, leak), by rows descending; adds up to total.
attacked_sitesinteger Distinct attacked sites.
ban_hitsinteger Revisits stopped by banned IPs - the sum of the auto_ban and status_ban items of blocked_by_feature. Always 0 until nodes tag ban blocks.
blockinteger Blocks in block mode (action = block, not observe).
block_reasonstring Block reason: region = blocked by region limit, region_log = region limit log-only hit (not blocked), acl = blocked by ACL, other = blocked by other protection; omitted when neither blocked nor a region-limit hit.
Values ["region","region_log","acl","other"]
blockedinteger Blocked requests (action = block).
blocked_aclinteger Requests blocked by ACLs (including ACLs without location conditions).
blocked_by_featureSecurityFeatureCount[] Blocked requests per protection feature (blocked requests scaled by sampling weight, challenges excluded). Always 12 items (genuine blocks only; leak and tamper protection replace the response body and are not listed here, see handled_by_feature), descending by count then in a fixed order; the counts add up to summary.blocked for the same window and site scope. A feature is derived from the rule_ref the node writes into the access log; blocks from nodes that do not tag them are counted under waf_rule.
blocked_regioninteger Requests blocked by the region limit.
body_truncboolean The request body exceeded the inspection limit and only the head was checked.
bot_scoreinteger Bot behaviour score 0–100; only on Bot events (type = bot), absent for other types (score is the WAF anomaly score and means something else).
bytes_sentinteger Raw downstream bytes.
cache_statusstring Cache status, such as HIT, MISS or BYPASS.
categorystring Rule category (sqli, xss, scanner, rce, php, nodejs, java, lfi, rfi, protocol, ...); empty when unknown.
challengeinteger Challenges outside observe mode (action = challenge).
checked_atstring Time of the checkup.
checkupobject Site checkup feed; the protection score (site checkup scores weighted by traffic) and the to-do suggestions. Follows site_id but not the time window.
client_ipstring Client IP; IPv4 as is.
comboobject Distribution of HTTP/2 and HTTP/3 combinations (number of sites).
compareSitesOverviewCompare The previous period (compare=prev) with its window [start, end), per-bucket points and totals; points align one-to-one with the current period. h3_ratio, backend_resp_time_p95 and noconfig_req are always null.
content_encodingstring Response Content-Encoding.
countinteger 530 count within the time window (sum across nodes).
countriesSecurityCountryCount[] Attack source countries (blocked and challenged requests scaled by sampling weight), descending; an empty country means unknown.
countrystring Client country (ISO 3166-1 alpha-2); omitted when unknown.
coveredinteger Known vulnerabilities of the recognised program already covered by built-in rules, from the protection list; 0 when no program is recognised or the list has no such product.
created_atstring Created at
criticalinteger Number of critical problems (ignored and locked ones excluded).
ctypestring Response Content-Type (parameters removed, lowercase).
current_site_idinteger Id of the site whose result is being saved; only present in stage 5 (stages 1-4 run on the whole batch and have no single current site), omitted otherwise.
cvesSecurityCve[] CVEs hit in the last 7 days (matched against the rule pack meta section), descending by hits, at most 50; empty when no rule pack is connected.
dimsobject Result of a dims request, mapping each dimension name to its ranking (which has no dims of its own); absent for a single-dimension request.
domainstring First domain.
done_rowsinteger Rows written to the file so far.
done_site_idsinteger[] Ids among the requested site_ids whose checkup results this batch has saved (ascending); sites not asked about are not listed, and the array is empty without site_ids (including the in-progress batch query). Requested sites missing here are not finished yet (or failed). Cleared when the batch is retried. See done_sites for the saved total.
done_sitesinteger Number of sites with saved results; below total_sites after completion means some sites failed.
errorstring Reason of the latest failure (kept while retrying, cleared once the export succeeds; the final reason when failed).
exceptionWafEventAllowException The site exception written by this allow-list action (or already present on the site).
expires_atstring When the file is removed (completion time plus the retention hours).
extrainteger Known vulnerabilities on the same basis that can additionally be covered once WAF rule updates are enabled.
facetsobject Facet counts for the filter buttons.
file_bytesinteger Compressed file size in bytes (set once done).
file_countinteger Number of uploaded files scanned in this request.
file_ctypestring Content-Type of the uploaded file as given by the client.
file_fieldstring Form field name of the uploaded file.
file_magicstring Type recognised from the file header; empty when unknown.
file_namestring Uploaded file name as given by the client; only on upload events (type = upload).
file_sha256string SHA-256 of the uploaded file; empty when not computed.
file_sizeinteger Uploaded file size in bytes; only on upload events (type = upload).
filterAccessLogExportFilter Filters given with the request (same as the list query parameters).
findingsCheckupFinding[] Checks with problems (passed checks are not listed), in check order.
finished_atstring Completion time.
first_seenstring When this problem began in its current run; omitted for the first checkup and for results saved before this was recorded.
first_seen_atstring Time of the earliest access log in the retention period; absent when there is none.
flowsSecurityFlow[] Attack flows top 50 (source country to the country and city of the node that took the traffic, blocked and challenged requests scaled by sampling weight), descending; the rest and nodes at unknown locations are merged into one trailing row with an empty node_country (not drawn); the total equals the total of countries. Part of WAF Enhanced, an empty array when it is off; only data written after the flow table was created is counted, so older windows are empty.
foreigninteger Requests from outside mainland China (known country other than CN); excluded from the ISP breakdown.
frequencystring Frequency: daily at 03:00, weekly on Monday at 03:00, or manual only.
Values ["daily","weekly","manual"]
geo_summaryTopGeoSummary Summary for the region dimensions (country, prov, isp) over the whole time window and the same filters, not limited by the number of ranked rows.
handled_by_featureSecurityHandledCount[] Requests handled by replacing content - leak and tamper protection rewrite the response body, keep the status code and are recorded as pass, so they are not blocks and are in neither blocked_by_feature nor summary.blocked, and should not enter block percentages. Only features with a count above 0 are listed, descending by count then leak before tamper; an empty array when there is no data (including before nodes tag body replacement), which the UI uses to hide it. Scaled by sampling weight and follows the time window and site scope.
headersstring[] First 20 request headers as "lowercase-name: value", values cut to 256 bytes; Cookie and Authorization values are masked.
historyCheckupHistoryPoint[] Scores of this site over the last 8 weeks.
hit_layerstring Upload scan layer that matched; empty when nothing matched.
hoststring Requested Host.
http2ProtocolSwitch Number of sites by switch state of a protocol (on, off, unset).
http3ProtocolSwitch Number of sites by switch state of a protocol (on, off, unset).
http_verstring HTTP protocol version (HTTP/x.y normalized to 1.0, 1.1, 2, 3).
https_offinteger Number of sites with HTTPS disabled.
https_oninteger Number of sites with HTTPS enabled.
idinteger Record ID
ignore_keysstring[] Check keys ignored for all sites (including sites added later), combined with per-site ignores. GET always returns it (empty array when none). Omit it on PUT to leave it unchanged; an empty array clears all; an unknown key returns 422. When set by an administrator it is platform-wide and applies to the sites of every tenant.
intel_hitboolean Whether the IP is currently in the platform high-risk IP library (looked up against the current library); null = the library is not being served, not judged.
intervalinteger Bucket width in seconds.
invalidinteger Number of sites whose configuration cannot be parsed or whose switch value is not a boolean.
ipstring The address looked up (canonical form).
ispstring Client ISP code; omitted when unknown.
ispsGeoCount[] Requests per ISP in mainland China, descending (empty key = ISP unknown).
itemsCheckupHistoryPoint[] Items on this page
ja4string Client TLS fingerprint JA4 (computed by the node during the TLS handshake, same for all requests on a connection); omitted for plain HTTP or when unavailable.
keysRequiredstring[] Check keys.
kindstring Site kind: domain (domain site) or ip (IP site); they have different edit pages.
Values ["domain","ip"]
last_seenstring Most recent minute it appeared.
last_seen_atstring Time of the latest access log in the retention period; absent when there is none.
levelstring Protection level of the site at the time: basic, standard or strict.
limitinteger Requests allowed per day (reports.access_log_export_daily; 0 = downloads not allowed).
log_onlyboolean Whether every platform-level automatic disposition (CC, SSL handshake, Bot, upload scanning, high-risk IP list, scanner, status-code ban) is still the factory log-only or off; admins only, omitted for tenants.
maxnumber bandwidth, backend_bandwidth: peak 5-minute bandwidth in the time window.
mediuminteger Number of medium problems.
messagestring Legacy note (action and score) kept for older clients; build texts from type, action and category instead.
methodstring HTTP request method.
metricsNodeRealtimeMetric[] Curves of each metric, in request order.
namestring Site name.
next_retry_atstring When the next retry starts (only for pending requests waiting to retry after a failure).
node_citystring City of the node that reported it; empty when only the country is known or the location is unknown.
node_idinteger ID of the node that served the request.
node_idsinteger[] Nodes that reported it (up to 50, ascending).
node_ipsstring[] Public addresses of the nodes in the site's own line groups (deduplicated and sorted, at most 500; private or management egress addresses are never listed); allow-listing them on the origin firewall restricts access to the CDN. Returned only when the origin-direct problem exists, otherwise an empty array.
node_latnumber Latitude of the node's landing point, as for node_lon.
node_lonnumber Longitude of the node's landing point (the city, or the country centroid when there is no city); absent when the location is unknown.
node_namesstring[] Node names in the same order as node_ids; "#<id>" if a node has no name or was deleted.
node_spotsSecurityNodeSpot[] Node landing points (country and city to the number of nodes in use), administrators only and always an empty array for tenants; same basis as the flows landing points (enabled primary nodes, nodes at unknown locations are not counted); independent of whether WAF Enhanced is on, the time window and site_id; descending by node count, then by country and city.
node_unknowninteger Number of nodes in use whose location is unknown (enabled primary nodes whose country cannot be determined, not counted in node_spots); administrators only, the field is absent from tenant responses; independent of whether WAF Enhanced is on, the time window and site_id.
nodesinteger Number of nodes that reported it.
notify_criticalboolean Raise an alert when a critical problem appears (uses the channels in alert settings).
observeboolean The site was in observe mode at the time (record only).
observe_ruleboolean true = the hit was a new rule still in its observation period, recorded only and not blocked (observe is then also true); emergency rules have no observation period, so always false.
opRequiredstring add puts keys on the ignore list (existing ones are untouched); remove takes them off.
Values ["add","remove"]
open_urlstring Clickable address of this request (the log's own scheme + host + non-default port + path and query); only http/https with a valid domain or IP and shorter than 2048 characters, otherwise omitted.
otherinteger The rest: log, mask or replace outside observe mode.
p95number bandwidth, backend_bandwidth: 95th percentile (5-minute samples for interval=5m, hourly peaks otherwise; only samples with data; the (n×5/100+1)-th largest, equal to the peak when n=1).
paramstring Name of the matched parameter, header or cookie; empty for unnamed locations.
paramsobject Numbers and names for display, same as params of this check in the checkup result (including open_url).
pathstring Limit to this path prefix; must equal the event URL path or be a prefix ending in / (e.g. /api/); a bare / must be combined with a rule or parameter. Omit for any path.
pointsSecurityPoint[] Attack trend; the bucket width follows the time span (about 288 points at most) and empty buckets are zero.
prefix_leninteger 32 (IPv4) or 64 (IPv6).
prev_scoreinteger Score of the previous checkup; null for the first checkup.
previousobject Comparison with the previous window of the same length.
probe_rulesCheckupProbeRule[] WAF rules matched in the last 7 days, summed per rule, most hits first, at most 10.
probesCheckupProbeExtra[] Rows of the last 7 days of probing that do not come from WAF events (CC cut, origin 404); WAF rule hits are in probe_rules.
progressinteger Progress percentage (rows written / total rows).
protocolstring HTTP version, e.g. HTTP/2.0.
provstring Client province (first two digits of GB/T 2260, mainland China only); omitted when unknown.
provincestring Province; empty when unknown.
provincesSecurityProvinceCount[] Attack source provinces in mainland China (blocked and challenged requests scaled by sampling weight), descending; requests with an unknown province are left out.
provsGeoCount[] Requests per mainland China province, descending (empty key = province unknown).
publish_seqinteger Publish sequence number triggered (when result = added).
reason_argsobject Parameters of the basis text (id site/cert id, at deletion time, domain the similar site domain, n differing characters, names node names, cname, ip, nodes, count).
reason_codestring Basis of the kind (message code; the panel renders the text per language): site_unsynced the site still
Values ["site_unsynced","site_disabled","site_deleted","cert_cover","bare_ip","bad_domain","typo","not_resolved","dns_error","nxdomain","nxdomain_random","pointed_a","pointed_cname","elsewhere_ip","elsewhere_cname","no_a","unavailable"]
recentWafEventRecent Events from the same IP in the past hour (total, rule breakdown, latest items).
refererstring Request Referer header.
referer_open_urlstring Clickable address of the Referer; omitted when it is not an http/https page (such as javascript: or android-app://), is malformed, or is 2048 characters or longer.
region_loggedinteger Requests matching a log-only region limit (not blocked).
remaininginteger Requests still available today.
request_idstring Request ID.
request_lengthinteger Request length in bytes.
request_time_msinteger Request processing time in milliseconds.
resetboolean true clears the override and returns to automatic detection (name and version are ignored).
resultstring added; exists = the site already has the same exception, nothing added; full = the exception list is full, nothing added.
Values ["added","exists","full"]
retriesinteger Number of failed attempts; when pending or running and above 0 the request is on retry N.
ruleboolean Skip only the matched rule (rule_ids); not allowed for non-rule events (rule id 0) or semantic events.
Default false
rule_idinteger ID of the rule that matched.
rule_namestring Short rule name.
rules_verstring Rule pack version; empty means the built-in rules.
runobject The batch in progress; omitted when there is none.
sample_factorinteger Sampling factor N (the largest sample_weight in the access logs read); 1 when not sampled.
sample_weightinteger Sampling weight (1 means not sampled).
sampledboolean The access logs read contain sampled rows (sample_weight > 1); counts are scaled by weight and incomplete.
saved_bytesinteger Origin traffic saved (bytes) - bytes sent to clients by requests served from cache and not blocked in the window, scaled by sampling weight.
scan_statusstring Upload scan result (type = upload); empty for other types.
scan_stepsstring[] Upload scan steps in order, one "layer:result" per layer.
schemestring Request scheme (http or https).
scoreinteger Checkup score (100 at most).
seriesLabeledLine[] Time series grouped by sub-object.
server_portinteger Port the request arrived on.
severitystring Severity of this problem on this site.
Values ["critical","medium","advice"]
site_deletedboolean true when the site this log belongs to has been deleted; omitted when the site still exists (or there is none).
site_idinteger Site ID
site_idsRequiredinteger[] Sites to process, at most 500.
site_namestring Name of the site it belongs to (primary domain, or the site name when it has none); for a deleted site the domain recorded when it was deleted, else the most common host in the last 7 days of access logs, omitted when none is found.
snippetstring Matched snippet (masked on the node; the value of the matched parameter or header). The list cuts it to the first 200 characters and the detail returns it whole. It carries no match offset, so it cannot be used to locate a highlight. For Bot events it is the triggering signal names.
source_ipsinteger Distinct source addresses.
stageinteger Current stage: 0 queued, 1 reading configuration, 2 counting logs, 3 direct probe, 4 per-check evaluation, 5 saving and alerting. With more than 200 sites the stage restarts for every batch of 200; evaluation is instantaneous on the server.
started_atstring Time the batch was created.
statestring State: pending, running, done, or failed after retries are exhausted.
Values ["pending","running","done","failed"]
statusstring Status: pending, running, done (downloadable), failed, or expired (file removed after the retention period).
Values ["pending","running","done","failed","expired"]
stepinteger Bucket width of series, in seconds.
summaryCheckupRunSummary Per-stage volume summary; a stage's key is absent until it is reached. Multi-batch tasks add up across batches.
tailboolean true = the tail row emitted when a sampling window closes; count is the number of other requests from the same source matching the same rule that were merged in the window, and the details (including URL) are copied from the window's first hit. Absent on ordinary rows.
targetstring Where it matched: uri, query_string, args, args_names, cookies, headers, body, ...
tenant_idinteger Owner tenant (user) ID of the site.
top_rulesSecurityRuleCount[] Top 10 matched rules (by hits, descending).
top_sitesSecuritySiteCount[] Top 10 attacked sites (by blocked and challenged requests, descending).
totalinteger Requests in the time window (scaled by sampling weight).
total_rowsinteger Total matching rows (counted when the export starts).
total_sitesinteger Number of sites in this batch; may still be 0 while queued.
totalsSitesOverviewTotals Totals over the time window.
traffic_monthinteger Month-to-date outbound bytes, from the 1st of the month containing end (Asia/Shanghai) up to end; sealed hours come from the 5-minute summary, later ones from live data.
traffic_todayinteger Today's outbound bytes, from midnight (Asia/Shanghai) of the day containing end up to end; same scope as totals.traffic.
truncatedboolean The matching rows exceeded the per-export limit (1,000,000 rows) and the file holds only the newest 1,000,000 rows (done_rows < total_rows); present only when done or expired.
tsstring Request time.
typestring Event type: rule, semantic, bot, upload scan, tamper protection or leak protection.
Values ["waf","semantic","bot","upload","tamper","leak"]
typesSecurityTypeCount[] Attack type distribution (WAF event hits by type), descending by count.
unavailablestring[] Supplementary items that could not be loaded this time (only present when the rule store or ClickHouse failed briefly; everything else is returned as usual and the missing items come back empty). coverage = covered / extra, probes = probes and probe_rules, node_ips = node_ips. Absent when everything loaded.
unknowninteger Requests whose country is unknown (no database, private address or not in the database).
unlimitedboolean true = no daily cap (administrators); limit and remaining are then absent.
upidinteger Origin (upstream) ID the request went to.
upstream_addrstring Origin address:port actually used; comma-separated hops when retried on another origin; empty when not fetched from origin.
upstream_bytesinteger Bytes received from the origin.
upstream_statusstring Status code returned by each origin hop, matching upstream_addr; empty when not fetched from origin.
upstream_time_msinteger Origin response time in milliseconds; null when not fetched from origin.
uristring Request URI including the query string.
urlstring Request path and query string (masked).
usedinteger Requests created today.
user_agentstring Request User-Agent header.
versionstring Application version; may be left empty.
window_mininteger Averaging window used, in minutes.
window_sinteger Window length in seconds.

Responses and errors

Success returns the resource JSON directly (HTTP 2xx); failures return application/problem+json (code, detail, plus errors on validation failures); lists carry items + total.

Success
{
  "id": 1,
  "name": "example"
}
List
{
  "items": [
    {
      "id": 1
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}
Error
{
  "code": "validation_failed",
  "detail": "Invalid request parameters",
  "errors": [
    {
      "code": "required",
      "field": "/name",
      "message": "name is required"
    }
  ],
  "request_id": "0123456789abcdef",
  "status": 422,
  "title": "Unprocessable Entity",
  "type": "about:blank"
}
Get started

Try the live demo

Open the live demo, or contact us for a quote and the install command