接口详情
GET /v1/analytics/blocked-ip-count
Count distinct client IPs blocked by the global firewall or CC auto-bans
- operationId
getTenantAnalyticsBlockedIPCount- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Requires a tenant-scoped identity with sites.read. Counts distinct client_ip values from global_firewall block events and CC temporary_ban events in the left-closed, right-open window and is bounded by one ingestion snapshot. It is not the current ACL cardinality.
参数
getTenantAnalyticsBlockedIPCount 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
from | query | string(date-time) | 是 | RFC3339 instant. After UTC normalization it must be exactly hour aligned and earlier than to. |
|---|
to | query | string(date-time) | 是 | Exclusive RFC3339 instant. After UTC normalization it must be exactly hour aligned. The window may not exceed 31 days. |
|---|
site_id | query | string(uuid) | 否 | — |
|---|
node_id | query | string(uuid) | 否 | — |
|---|
响应
getTenantAnalyticsBlockedIPCount 响应| 状态码 | 说明 |
|---|
200 | Distinct client IPs blocked by global firewall events or auto-banned by CC rules in the normalized UTC window. 字段：blocked_ip_count: integer(uint64) meta: QueryMetadata |
|---|
400 | analytics_invalid_request |
|---|
401 | analytics_authentication_required |
|---|
403 | analytics_permission_denied or analytics_scope_forbidden |
|---|
408 | analytics_request_cancelled |
|---|
502 | analytics_storage_rejected, analytics_storage_invalid_response, or analytics_response_too_large |
|---|
503 | analytics_storage_unavailable or analytics_realtime_evidence_unavailable; no zero-value data is substituted. site-realtime with query_version=3 returns partial coverage instead of analytics_realtime_evidence_unavailable for unsettled hours; dependency failures remain 503. |
|---|
504 | analytics_query_timeout |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/analytics/blocked-ip-trend
Read the hourly distinct client IPs blocked by the global firewall
- operationId
getTenantAnalyticsBlockedIPTrend- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Requires a tenant-scoped identity with sites.read. Each returned UTC bucket contains the distinct client_ip count from global_firewall block events, bounded by one ingestion snapshot.
参数
getTenantAnalyticsBlockedIPTrend 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
from | query | string(date-time) | 是 | RFC3339 instant. After UTC normalization it must be exactly hour aligned and earlier than to. |
|---|
to | query | string(date-time) | 是 | Exclusive RFC3339 instant. After UTC normalization it must be exactly hour aligned. The window may not exceed 31 days. |
|---|
site_id | query | string(uuid) | 否 | — |
|---|
node_id | query | string(uuid) | 否 | — |
|---|
响应
getTenantAnalyticsBlockedIPTrend 响应| 状态码 | 说明 |
|---|
200 | Hourly distinct client IPs blocked by global firewall events. 字段：data: array<BlockedIPTrendPoint> meta: QueryMetadata |
|---|
400 | analytics_invalid_request |
|---|
401 | analytics_authentication_required |
|---|
403 | analytics_permission_denied or analytics_scope_forbidden |
|---|
408 | analytics_request_cancelled |
|---|
502 | analytics_storage_rejected, analytics_storage_invalid_response, or analytics_response_too_large |
|---|
503 | analytics_storage_unavailable or analytics_realtime_evidence_unavailable; no zero-value data is substituted. site-realtime with query_version=3 returns partial coverage instead of analytics_realtime_evidence_unavailable for unsettled hours; dependency failures remain 503. |
|---|
504 | analytics_query_timeout |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/analytics/connections/dead-letters
List durable analytics connections dead-letter receipts
- operationId
listTenantAnalyticsConnectionsDeadLetters- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Requires a revocable tenant Bearer session with sites.read. Tenant scope is derived exclusively from that session; the response is a digest-only durable receipt projection with no raw payload.
参数
listTenantAnalyticsConnectionsDeadLetters 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
limit | query | integer | 否 | — |
|---|
after_sequence | query | integer(uint64) | 否 | Exclusive decimal JetStream dead-letter stream sequence cursor. |
|---|
响应
listTenantAnalyticsConnectionsDeadLetters 响应| 状态码 | 说明 |
|---|
200 | Digest-only durable DLQ receipts ordered by dead-letter stream sequence. 字段：items: array<ConnectionsDeadLetterItem> next_after_sequence?: integer(uint64) |
|---|
400 | connections_dead_letter_invalid_request |
|---|
401 | connections_dead_letter_authentication_required |
|---|
403 | connections_dead_letter_permission_denied |
|---|
404 | connections_dead_letter_not_found |
|---|
408 | connections_dead_letter_request_timeout |
|---|
502 | connections_dead_letter_invalid_response or connections_dead_letter_response_too_large |
|---|
503 | connections_dead_letter_unavailable; no zero-value receipt is substituted. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/analytics/connections/dead-letters/{dead_letter_id}
Read one durable analytics connections dead-letter receipt
- operationId
getTenantAnalyticsConnectionsDeadLetter- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Requires a revocable tenant Bearer session with sites.read. The tenant scope is derived exclusively from the session and raw payload is never returned.
参数
getTenantAnalyticsConnectionsDeadLetter 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
dead_letter_id | path | string | 是 | — |
|---|
响应
getTenantAnalyticsConnectionsDeadLetter 响应| 状态码 | 说明 |
|---|
200 | One digest-only durable DLQ receipt. 字段：item: ConnectionsDeadLetterItem |
|---|
400 | connections_dead_letter_invalid_request |
|---|
401 | connections_dead_letter_authentication_required |
|---|
403 | connections_dead_letter_permission_denied |
|---|
404 | connections_dead_letter_not_found |
|---|
408 | connections_dead_letter_request_timeout |
|---|
502 | connections_dead_letter_invalid_response or connections_dead_letter_response_too_large |
|---|
503 | connections_dead_letter_unavailable; no zero-value receipt is substituted. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/analytics/connections/retention
Read finalized connections retention facts for the authenticated tenant
- operationId
getTenantAnalyticsConnectionsRetention- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Requires a revocable tenant Bearer session with sites.read. Tenant scope is derived exclusively from that session; tenant_id is rejected.
参数
getTenantAnalyticsConnectionsRetention 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
subscription_id | query | string(uuid) | 是 | Package subscription authority captured at event time. |
|---|
from | query | string(date-time) | 是 | Inclusive canonical UTC RFC3339 instant. |
|---|
to | query | string(date-time) | 是 | Exclusive canonical UTC RFC3339 instant; the window may not exceed 31 days. |
|---|
limit | query | integer | 否 | — |
|---|
响应
getTenantAnalyticsConnectionsRetention 响应| 状态码 | 说明 |
|---|
200 | Finalized connections facts in ascending period order. 字段：items: array<ConnectionsRetentionItem> |
|---|
400 | retention_invalid_request |
|---|
401 | retention_authentication_required |
|---|
403 | retention_permission_denied |
|---|
408 | retention_request_timeout |
|---|
502 | retention_invalid_response or retention_response_too_large |
|---|
503 | retention_unavailable; no zero-value fact is substituted. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/analytics/hourly-trend
Read the authenticated tenant hourly trend
- operationId
getTenantAnalyticsHourlyTrend- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Requires a tenant-scoped identity with sites.read. Buckets are UTC hours and only buckets containing events are returned.
参数
getTenantAnalyticsHourlyTrend 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
from | query | string(date-time) | 是 | RFC3339 instant. After UTC normalization it must be hour aligned and earlier than to. |
|---|
to | query | string(date-time) | 是 | Exclusive RFC3339 instant. It must be hour aligned after UTC normalization; the window is at most 31 days. |
|---|
site_id | query | string(uuid) | 否 | — |
|---|
node_id | query | string(uuid) | 否 | — |
|---|
响应
getTenantAnalyticsHourlyTrend 响应| 状态码 | 说明 |
|---|
200 | UTC hourly metrics ordered by hour ascending; hours with no events are omitted. 字段：data: array<AnalyticsTrendPoint> meta: AnalyticsQueryMetadata |
|---|
400 | analytics_invalid_request |
|---|
401 | analytics_authentication_required |
|---|
403 | analytics_permission_denied or analytics_scope_forbidden |
|---|
408 | analytics_request_cancelled |
|---|
500 | analytics_internal_error |
|---|
502 | analytics_storage_rejected, analytics_storage_invalid_response, or analytics_response_too_large |
|---|
503 | analytics_storage_unavailable; no zero-value data is substituted. |
|---|
504 | analytics_query_timeout |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/analytics/l4-realtime
- operationId
getTenantL4Realtime- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
参数
getTenantL4Realtime 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
range | query | string: 1h / 6h / 12h / 24h / custom | 是 | — |
|---|
timezone | query | string | 是 | — |
|---|
from | query | string(date-time) | 否 | — |
|---|
to | query | string(date-time) | 否 | — |
|---|
site_id | query | string(uuid) | 否 | — |
|---|
stream_id | query | string(uuid) | 否 | — |
|---|
node_id | query | string(uuid) | 否 | — |
|---|
protocol | query | string: tcp / udp | 否 | — |
|---|
listen_port | query | integer | 否 | — |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | — |
|---|
响应
getTenantL4Realtime 响应| 状态码 | 说明 |
|---|
200 | L4 session aggregates 字段：version: string meta: object totals: object rows: array<object> next_cursor?: string |
|---|
400 | Request validation failed; clients map the stable code through locale resources. |
|---|
401 | Authentication is required or the session is invalid. |
|---|
403 | The authenticated principal cannot access this scope or operation. |
|---|
500 | The response could not be encoded safely. |
|---|
503 | The analytics dependency is unavailable; retry with the same query. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/analytics/logs/access
List access logs for the authenticated tenant
- operationId
listTenantAccessLogs- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Scope comes only from the authenticated tenant identity. Supplying tenant_id, even with the same value, returns 403.
参数
listTenantAccessLogs 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
from | query | string(date-time) | 是 | Inclusive RFC3339 instant with at most millisecond precision. It is normalized to UTC and must be earlier than to. |
|---|
to | query | string(date-time) | 是 | Exclusive RFC3339 instant with at most millisecond precision. The window may not exceed 31 days. |
|---|
site_id | query | string(uuid) | 否 | — |
|---|
host | query | string | 否 | Access logs and block events: one host or up to 64 distinct space-separated hosts. |
|---|
node_id | query | string(uuid) | 否 | — |
|---|
client_ip | query | string(ip) | 否 | Exact IPv4 or IPv6 address without a zone identifier. |
|---|
uri_path | query | string | 否 | Exact origin-form path after query and fragment removal. |
|---|
uri_path_match | query | string: exact / prefix | 否 | How uri_path matches; prefix uses a startsWith match on the origin-form path. Requires uri_path. |
|---|
status_code | query | integer | 否 | — |
|---|
method | query | string | 否 | Exact HTTP method; access-log routes only. |
|---|
protocol | query | string | 否 | Exact stored protocol; access-log routes only. |
|---|
cache_status | query | string | 否 | Exact stored cache status; access-log routes only. |
|---|
upstream_result | query | string | 否 | — |
|---|
content_type | query | string | 否 | — |
|---|
user_agent | query | string | 否 | — |
|---|
request_bytes_min | query | integer(uint64) | 否 | — |
|---|
request_bytes_max | query | integer(uint64) | 否 | — |
|---|
response_bytes_min | query | integer(uint64) | 否 | — |
|---|
response_bytes_max | query | integer(uint64) | 否 | — |
|---|
country_code | query | string | 否 | Exact stored country or region code. |
|---|
carrier | query | string | 否 | Exact stored carrier value. |
|---|
ja4 | query | string | 否 | Exact stored JA4 fingerprint. Rows without a source JA4 do not match. |
|---|
origin_connect_us_min | query | integer(uint64) | 否 | — |
|---|
origin_connect_us_max | query | integer(uint64) | 否 | — |
|---|
origin_first_byte_us_min | query | integer(uint64) | 否 | — |
|---|
origin_first_byte_us_max | query | integer(uint64) | 否 | — |
|---|
origin_total_us_min | query | integer(uint64) | 否 | — |
|---|
origin_total_us_max | query | integer(uint64) | 否 | — |
|---|
limit | query | integer | 否 | Page size. When more rows exist at the fixed snapshot, the response includes an opaque next_cursor. |
|---|
cursor | query | string | 否 | Opaque keyset cursor returned by the preceding page. It is bound to the tenant, route kind, complete filter, descending direction, snapshot, and last (occurred_at,event_id) key. Malformed, overlong, or mismatched cursors are rejected and never re-scoped. |
|---|
响应
listTenantAccessLogs 响应| 状态码 | 说明 |
|---|
200 | Snapshot-bounded access-log page. 字段：data: array<AccessLog> meta: QueryMetadata |
|---|
400 | Invalid GET body, time range, filter, limit, cursor, or required platform tenant scope. GET bodies are never read. |
|---|
401 | Authentication is required. |
|---|
403 | Permission or identity scope is forbidden. |
|---|
404 | Analytics log route was not found. |
|---|
422 | Returns analytics_logs_capability_unsupported for malformed cursor shapes rejected before storage or physically observable equal-version replacement ambiguity. |
|---|
503 | Storage transport, rejection, invalid response, or response limit failure. |
|---|
504 | Query deadline or caller cancellation was observed. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/analytics/logs/access/exports
List durable access-log exports owned by the calling tenant account
- operationId
listTenantAccessLogExports- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Without query filters, lists up to 50 exports owned by the calling account (user + access scope), regardless of the login session that created them. With from/to (and the same filters as the access-log list, without limit/cursor), returns at most one export: the latest generation for that account and normalized query scope, so the log view can recover it after re-login.
参数
listTenantAccessLogExports 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
from | query | string(date-time) | 否 | Export scope lookup; when present, to is required and the filters follow the access-log list. |
|---|
to | query | string(date-time) | 否 | Export scope lookup; exclusive end of the window. |
|---|
site_id | query | string(uuid) | 否 | — |
|---|
host | query | string | 否 | Access logs and block events: one host or up to 64 distinct space-separated hosts. |
|---|
node_id | query | string(uuid) | 否 | — |
|---|
client_ip | query | string(ip) | 否 | Exact IPv4 or IPv6 address without a zone identifier. |
|---|
uri_path | query | string | 否 | Exact origin-form path after query and fragment removal. |
|---|
uri_path_match | query | string: exact / prefix | 否 | How uri_path matches; prefix uses a startsWith match on the origin-form path. Requires uri_path. |
|---|
status_code | query | integer | 否 | — |
|---|
method | query | string | 否 | Exact HTTP method; access-log routes only. |
|---|
protocol | query | string | 否 | Exact stored protocol; access-log routes only. |
|---|
cache_status | query | string | 否 | Exact stored cache status; access-log routes only. |
|---|
upstream_result | query | string | 否 | — |
|---|
content_type | query | string | 否 | — |
|---|
user_agent | query | string | 否 | — |
|---|
request_bytes_min | query | integer(uint64) | 否 | — |
|---|
request_bytes_max | query | integer(uint64) | 否 | — |
|---|
response_bytes_min | query | integer(uint64) | 否 | — |
|---|
response_bytes_max | query | integer(uint64) | 否 | — |
|---|
country_code | query | string | 否 | Exact stored country or region code. |
|---|
carrier | query | string | 否 | Exact stored carrier value. |
|---|
ja4 | query | string | 否 | Exact stored JA4 fingerprint. Rows without a source JA4 do not match. |
|---|
origin_connect_us_min | query | integer(uint64) | 否 | — |
|---|
origin_connect_us_max | query | integer(uint64) | 否 | — |
|---|
origin_first_byte_us_min | query | integer(uint64) | 否 | — |
|---|
origin_first_byte_us_max | query | integer(uint64) | 否 | — |
|---|
origin_total_us_min | query | integer(uint64) | 否 | — |
|---|
origin_total_us_max | query | integer(uint64) | 否 | — |
|---|
响应
listTenantAccessLogExports 响应| 状态码 | 说明 |
|---|
200 | At most 50 exports for the exact actor, session, scope and tenant. 字段：data: array<AccessExport> |
|---|
400 | Invalid GET body, time range, filter, limit, cursor, or required platform tenant scope. GET bodies are never read. |
|---|
401 | Authentication is required. |
|---|
403 | Permission or identity scope is forbidden. |
|---|
503 | Storage transport, rejection, invalid response, or response limit failure. |
|---|
504 | Query deadline or caller cancellation was observed. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/analytics/logs/access/exports
Create a snapshot-bound access-log export for the current tenant
- operationId
createTenantAccessLogExport- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Idempotent per account (user + access scope) and normalized query scope, independent of the login session. The same Idempotency-Key replays its export (409 if the key was used for another scope). For the same scope, a pending, running or unexpired completed export is reused (Idempotency-Replayed: true); a failed export with attempts left is retried in place under the same export id; otherwise a new generation is created.
参数
createTenantAccessLogExport 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
createTenantAccessLogExport 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
filter | AccessExportFilter | 是 | — |
|---|
响应
createTenantAccessLogExport 响应| 状态码 | 说明 |
|---|
202 | Durable export request accepted; an identical idempotency replay returns the same job. 字段：id: string(uuid) status: string: pending / running / completed / failed reason: string snapshot_at: string(date-time) | null(date-time) row_count: integer | null byte_count: integer | null sha256?: string created_at: string(date-time) expires_at: string(date-time) | null(date-time) downloadable: boolean filter: AccessExportFilter | null |
|---|
400 | Invalid GET body, time range, filter, limit, cursor, or required platform tenant scope. GET bodies are never read. |
|---|
401 | Authentication is required. |
|---|
403 | Permission or identity scope is forbidden. |
|---|
409 | Idempotency key is already bound to another normalized export request. |
|---|
503 | Storage transport, rejection, invalid response, or response limit failure. |
|---|
504 | Query deadline or caller cancellation was observed. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/analytics/logs/access/exports/{export_id}
- operationId
getTenantAccessLogExport- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
参数
getTenantAccessLogExport 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
export_id | path | string(uuid) | 是 | — |
|---|
响应
getTenantAccessLogExport 响应| 状态码 | 说明 |
|---|
200 | Session-bound durable export status. 字段：id: string(uuid) status: string: pending / running / completed / failed reason: string snapshot_at: string(date-time) | null(date-time) row_count: integer | null byte_count: integer | null sha256?: string created_at: string(date-time) expires_at: string(date-time) | null(date-time) downloadable: boolean filter: AccessExportFilter | null |
|---|
400 | Invalid GET body, time range, filter, limit, cursor, or required platform tenant scope. GET bodies are never read. |
|---|
401 | Authentication is required. |
|---|
403 | Permission or identity scope is forbidden. |
|---|
404 | Analytics log route was not found. |
|---|
503 | Storage transport, rejection, invalid response, or response limit failure. |
|---|
504 | Query deadline or caller cancellation was observed. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/analytics/logs/access/exports/{export_id}/download
- operationId
downloadTenantAccessLogExport- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
参数
downloadTenantAccessLogExport 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
export_id | path | string(uuid) | 是 | — |
|---|
X-Analytics-Download-Token | header | string | 是 | Short-lived one-time token. The server stores only its SHA-256 digest. |
|---|
响应
downloadTenantAccessLogExport 响应| 状态码 | 说明 |
|---|
200 | RFC4180 UTF-8 CSV consumed atomically by the one-time grant. |
|---|
400 | Invalid GET body, time range, filter, limit, cursor, or required platform tenant scope. GET bodies are never read. |
|---|
401 | Authentication is required. |
|---|
403 | Permission or identity scope is forbidden. |
|---|
410 | Grant is malformed, expired, consumed, or belongs to another session or scope. |
|---|
503 | Storage transport, rejection, invalid response, or response limit failure. |
|---|
504 | Query deadline or caller cancellation was observed. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/analytics/logs/access/exports/{export_id}/download-grants
- operationId
grantTenantAccessLogExportDownload- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Returns a short-lived one-time token bound to the current tenant session and export. Any session of the owning account may request a grant; a token from another session is rejected. API keys are rejected.
参数
grantTenantAccessLogExportDownload 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
export_id | path | string(uuid) | 是 | — |
|---|
响应
grantTenantAccessLogExportDownload 响应| 状态码 | 说明 |
|---|
201 | One-time grant. Only the SHA-256 token digest is persisted. 字段：export_id: string(uuid) token: string expires_at: string(date-time) |
|---|
400 | Invalid GET body, time range, filter, limit, cursor, or required platform tenant scope. GET bodies are never read. |
|---|
401 | Authentication is required. |
|---|
403 | Permission or identity scope is forbidden. |
|---|
404 | Analytics log route was not found. |
|---|
503 | Storage transport, rejection, invalid response, or response limit failure. |
|---|
504 | Query deadline or caller cancellation was observed. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/analytics/logs/block-events
List security block events for the authenticated tenant
- operationId
listTenantBlockEvents- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Scope comes only from the authenticated tenant identity. Returns the current security-event projection with snapshot-bounded keyset pagination. This route does not claim immutable block-state history.
参数
listTenantBlockEvents 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
from | query | string(date-time) | 是 | Inclusive RFC3339 instant with at most millisecond precision. It is normalized to UTC and must be earlier than to. |
|---|
to | query | string(date-time) | 是 | Exclusive RFC3339 instant with at most millisecond precision. The window may not exceed 31 days. |
|---|
site_id | query | string(uuid) | 否 | — |
|---|
node_id | query | string(uuid) | 否 | — |
|---|
client_ip | query | string(ip) | 否 | Exact IPv4 or IPv6 address without a zone identifier. |
|---|
uri_path | query | string | 否 | Exact origin-form path after query and fragment removal. |
|---|
uri_path_match | query | string: exact / prefix | 否 | How uri_path matches; prefix uses a startsWith match on the origin-form path. Requires uri_path. |
|---|
status_code | query | const 0 | integer | 否 | Exact stored status; 0 means no HTTP status was recorded. |
|---|
action | query | string: block / challenge / log / temporary_ban | 否 | Block events only: narrow to block, challenge, log (observed) or temporary_ban (auto block); default all four, the hits the WAF overview counts. A CC challenge page / 429 is one event per site, client IP, rule, action and minute with its request count. |
|---|
event_type | query | string | 否 | Block events only: narrow to one event type (waf, cc, acl, ...). |
|---|
host | query | string | 否 | Access logs and block events: one host or up to 64 distinct space-separated hosts. |
|---|
country_code | query | string | 否 | Exact stored country or region code. |
|---|
carrier | query | string | 否 | Exact stored carrier value. |
|---|
ja4 | query | string | 否 | Exact stored JA4 fingerprint. Rows without a source JA4 do not match. |
|---|
origin_connect_us_min | query | integer(uint64) | 否 | — |
|---|
origin_connect_us_max | query | integer(uint64) | 否 | — |
|---|
origin_first_byte_us_min | query | integer(uint64) | 否 | — |
|---|
origin_first_byte_us_max | query | integer(uint64) | 否 | — |
|---|
origin_total_us_min | query | integer(uint64) | 否 | — |
|---|
origin_total_us_max | query | integer(uint64) | 否 | — |
|---|
limit | query | integer | 否 | Page size. When more rows exist at the fixed snapshot, the response includes an opaque next_cursor. |
|---|
cursor | query | string | 否 | Opaque keyset cursor returned by the preceding page. It is bound to the tenant, route kind, complete filter, descending direction, snapshot, and last (occurred_at,event_id) key. Malformed, overlong, or mismatched cursors are rejected and never re-scoped. |
|---|
响应
listTenantBlockEvents 响应| 状态码 | 说明 |
|---|
200 | Snapshot-bounded security block-event page. 字段：data: array<BlockEvent> meta: QueryMetadata |
|---|
400 | Invalid GET body, time range, filter, limit, cursor, or required platform tenant scope. GET bodies are never read. |
|---|
401 | Authentication is required. |
|---|
403 | Permission or identity scope is forbidden. |
|---|
404 | Analytics log route was not found. |
|---|
422 | Returns analytics_logs_capability_unsupported for malformed cursor shapes rejected before storage or physically observable equal-version replacement ambiguity. |
|---|
503 | Storage transport, rejection, invalid response, or response limit failure. |
|---|
504 | Query deadline or caller cancellation was observed. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/analytics/logs/blocks/current
List current ACL blocks for the authenticated tenant
- operationId
listTenantCurrentBlocks- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Scope comes only from the authenticated tenant identity. Supplying a tenant_id is rejected rather than re-scoping the request.
参数
listTenantCurrentBlocks 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
site_id | query | string(uuid) | 否 | — |
|---|
limit | query | integer | 否 | Maximum current or historical block facts returned. |
|---|
offset | query | integer | 否 | Number of matching current or historical block facts to skip. |
|---|
响应
listTenantCurrentBlocks 响应| 状态码 | 说明 |
|---|
200 | Current active ACL block facts. 字段：data: array<CurrentBlock> total_count: integer(uint64) snapshot_at: string(date-time) |
|---|
400 | Invalid GET body, time range, filter, limit, cursor, or required platform tenant scope. GET bodies are never read. |
|---|
401 | Authentication is required. |
|---|
403 | Permission or identity scope is forbidden. |
|---|
404 | Analytics log route was not found. |
|---|
503 | Storage transport, rejection, invalid response, or response limit failure. |
|---|
504 | Query deadline or caller cancellation was observed. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/analytics/logs/blocks/current-count
Count current ACL blocks by site for the authenticated tenant
- operationId
countTenantCurrentBlocksBySite- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
响应
countTenantCurrentBlocksBySite 响应| 状态码 | 说明 |
|---|
200 | Current active ACL block totals grouped by site. 字段：data: array<SiteBlacklistCount> total_count: integer(uint64) snapshot_at: string(date-time) |
|---|
400 | Invalid GET body, time range, filter, limit, cursor, or required platform tenant scope. GET bodies are never read. |
|---|
401 | Authentication is required. |
|---|
403 | Permission or identity scope is forbidden. |
|---|
503 | Storage transport, rejection, invalid response, or response limit failure. |
|---|
504 | Query deadline or caller cancellation was observed. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/analytics/logs/blocks/current/{block_id}/unlock
Unlock one current ACL block for the authenticated tenant
- operationId
unlockTenantCurrentBlock- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.manage
说明（契约原文）
Uses only the authenticated tenant scope and the same policy revision, idempotency, activation and conflict contract as the platform route.
参数
unlockTenantCurrentBlock 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
block_id | path | string(uuid) | 是 | Stable identity derived from site, active ACL policy and canonical CIDR. |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
unlockTenantCurrentBlock 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
reason_code | string | 是 | — |
|---|
响应
unlockTenantCurrentBlock 响应| 状态码 | 说明 |
|---|
202 | The successor policy and activation were durably accepted. 字段：block_id: string(uuid) candidate_id: string(uuid) progress: string: claimed / canary / expanding / healthy / failed / cancelled / expired / promoted reason_code: string: recovery_claimed / recovery_replayed replayed: boolean |
|---|
400 | Invalid GET body, time range, filter, limit, cursor, or required platform tenant scope. GET bodies are never read. |
|---|
401 | Authentication is required. |
|---|
403 | Permission or identity scope is forbidden. |
|---|
404 | The scoped active block no longer exists. |
|---|
409 | Returns analytics_block_unlock_conflict when the policy, active edge revision, open activation or target-node snapshot changed. |
|---|
503 | Storage transport, rejection, invalid response, or response limit failure. |
|---|
504 | Query deadline or caller cancellation was observed. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/analytics/logs/blocks/history
List audited unlock history for the authenticated tenant
- operationId
listTenantBlockHistory- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Scope comes only from the authenticated tenant identity. Raw security events remain available from the separate block-events route.
参数
listTenantBlockHistory 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
site_id | query | string(uuid) | 否 | — |
|---|
limit | query | integer | 否 | Maximum current or historical block facts returned. |
|---|
offset | query | integer | 否 | Number of matching current or historical block facts to skip. |
|---|
响应
listTenantBlockHistory 响应| 状态码 | 说明 |
|---|
200 | Append-only CIDR unlock history with durable edge progress. 字段：data: array<BlockHistory> total_count: integer(uint64) snapshot_at: string(date-time) |
|---|
400 | Invalid GET body, time range, filter, limit, cursor, or required platform tenant scope. GET bodies are never read. |
|---|
401 | Authentication is required. |
|---|
403 | Permission or identity scope is forbidden. |
|---|
404 | Analytics log route was not found. |
|---|
503 | Storage transport, rejection, invalid response, or response limit failure. |
|---|
504 | Query deadline or caller cancellation was observed. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/analytics/logs/cc-coordination
List cross-node CC coordination states of the authenticated tenant, optionally narrowed to one site
- operationId
listTenantCCCoordinationStates- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
参数
listTenantCCCoordinationStates 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
site_id | query | string(uuid) | 否 | — |
|---|
limit | query | integer | 否 | Maximum current or historical block facts returned. |
|---|
响应
listTenantCCCoordinationStates 响应| 状态码 | 说明 |
|---|
200 | Durable tenant/site-scoped cross-node CC state. 字段：items: array<CCCoordinationState> |
|---|
400 | Invalid GET body, time range, filter, limit, cursor, or required platform tenant scope. GET bodies are never read. |
|---|
401 | Authentication is required. |
|---|
403 | Permission or identity scope is forbidden. |
|---|
503 | Storage transport, rejection, invalid response, or response limit failure. |
|---|
504 | Query deadline or caller cancellation was observed. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/analytics/logs/cc-coordination/{state_id}/release
Release one exact cross-node CC state for the authenticated tenant
- operationId
releaseTenantCCCoordinationState- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.manage
参数
releaseTenantCCCoordinationState 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
state_id | path | string(uuid) | 是 | — |
|---|
site_id | query | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
X-Request-ID | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
releaseTenantCCCoordinationState 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
reason_code | string | 是 | — |
|---|
expected_generation | integer(int64) | 是 | — |
|---|
响应
releaseTenantCCCoordinationState 响应| 状态码 | 说明 |
|---|
202 | The exact generation was accepted for audited release. 字段：state: CCCoordinationState replayed: boolean |
|---|
400 | Invalid GET body, time range, filter, limit, cursor, or required platform tenant scope. GET bodies are never read. |
|---|
401 | Authentication is required. |
|---|
403 | Permission or identity scope is forbidden. |
|---|
409 | Returns analytics_block_unlock_conflict when the policy, active edge revision, open activation or target-node snapshot changed. |
|---|
503 | Storage transport, rejection, invalid response, or response limit failure. |
|---|
504 | Query deadline or caller cancellation was observed. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/analytics/logs/{kind}/geo-evidence/{event_id}
Reconcile one authenticated tenant log fact against a verified GeoIP catalog
- operationId
getTenantAnalyticsGeoEvidence- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
tenant_id is forbidden; the tenant comes only from authenticated identity. The raw address is never returned.
参数
getTenantAnalyticsGeoEvidence 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
kind | path | string: access / block | 是 | — |
|---|
event_id | path | string | 是 | — |
|---|
from | query | string(date-time) | 是 | — |
|---|
to | query | string(date-time) | 是 | — |
|---|
site_id | query | string(uuid) | 是 | — |
|---|
node_id | query | string(uuid) | 是 | — |
|---|
client_ip | query | string(ip) | 是 | — |
|---|
database_version | query | string | 否 | — |
|---|
响应
getTenantAnalyticsGeoEvidence 响应| 状态码 | 说明 |
|---|
200 | Verified bounded geo evidence. 字段：data: Evidence |
|---|
400 | Invalid request. |
|---|
401 | Stable error envelope. |
|---|
403 | Stable error envelope. |
|---|
404 | Stable error envelope. |
|---|
408 | Stable error envelope. |
|---|
409 | Stable error envelope. |
|---|
502 | Stable error envelope. |
|---|
503 | Stable error envelope. |
|---|
504 | Stable error envelope. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/analytics/market-security
List relayed market supply attack log lines of the session tenant
- operationId
listMarketSecurityLogs- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
参数
listMarketSecurityLogs 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
from | query | string(date-time) | 是 | RFC 3339; at most 31 days before to. |
|---|
to | query | string(date-time) | 是 | — |
|---|
site_id | query | string(uuid) | 否 | — |
|---|
client_ip | query | string | 否 | — |
|---|
host | query | string | 否 | — |
|---|
cursor | query | string | 否 | meta.next_cursor of the previous page. |
|---|
limit | query | integer | 否 | — |
|---|
响应
listMarketSecurityLogs 响应| 状态码 | 说明 |
|---|
200 | Newest first. 字段：data: array<Log> meta: object |
|---|
400 | Error. |
|---|
401 | Error. |
|---|
403 | Error. |
|---|
405 | Error. |
|---|
503 | Error. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/analytics/site-monitoring
Read site monitoring for the authenticated tenant
- operationId
getTenantSiteMonitoring- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Requires a tenant session with sites.read. The tenant is derived only from the authenticated principal; tenant_id and self-asserted identity headers are rejected. Query parameters are single-valued and strict.
参数
getTenantSiteMonitoring 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
range | query | string: 1h / 6h / 12h / custom | 是 | Fixed presets use no from/to values. custom requires both from and to and is limited to 31 days; longer ranges are rejected. |
|---|
from | query | string(date-time) | 否 | Inclusive UTC boundary, required only for range=custom. |
|---|
to | query | string(date-time) | 否 | Exclusive UTC boundary, required only for range=custom. |
|---|
timezone | query | string | 是 | — |
|---|
site_id | query | string(uuid) | 否 | — |
|---|
node_id | query | string(uuid) | 否 | — |
|---|
domain | query | string | 否 | — |
|---|
listen_port | query | integer | 否 | — |
|---|
rank_by | query | string: host / site / node / status_code | 否 | — |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | Opaque snapshot- and filter-bound cursor. |
|---|
X-Request-ID | header | string | 否 | — |
|---|
响应
getTenantSiteMonitoring 响应| 状态码 | 说明 |
|---|
200 | Finalized monitoring aggregate. 字段：version: string meta: SiteMonitoringMeta basic: AvailableBasic | DegradedSection quality: AvailableQuality | DegradedSection origin: AvailableOrigin | DegradedSection rank: AvailableRank | DegradedSection |
|---|
400 | Stable non-leaking error envelope. |
|---|
401 | Stable non-leaking error envelope. |
|---|
403 | Stable non-leaking error envelope. |
|---|
405 | Stable non-leaking error envelope. |
|---|
408 | Stable non-leaking error envelope. |
|---|
502 | Stable non-leaking error envelope. |
|---|
503 | Stable non-leaking error envelope. |
|---|
504 | Stable non-leaking error envelope. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/analytics/site-quality-diagnostics
Read tenant quality diagnostics from finalized access facts
- operationId
getTenantQualityDiagnostics- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
参数
getTenantQualityDiagnostics 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
from | query | string(date-time) | 是 | Inclusive UTC millisecond boundary. |
|---|
to | query | string(date-time) | 是 | Exclusive UTC millisecond boundary, at most 31 days after from. |
|---|
site_id | query | string(uuid) | 否 | — |
|---|
node_id | query | string(uuid) | 否 | — |
|---|
category | query | string: upstream_5xx / edge_530 / no_host / config_mismatch | 否 | — |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | — |
|---|
响应
getTenantQualityDiagnostics 响应| 状态码 | 说明 |
|---|
200 | Finalized, latest-state diagnostics at one exact snapshot. 字段：items: array<QualityDiagnostic> next_cursor: string | null snapshot: FinalizedSnapshot effective_tenant_id?: string(uuid) |
|---|
400 | Stable error response with no raw dependency text. |
|---|
401 | Stable error response with no raw dependency text. |
|---|
403 | Stable error response with no raw dependency text. |
|---|
405 | Stable error response with no raw dependency text. |
|---|
408 | Stable error response with no raw dependency text. |
|---|
409 | Stable error response with no raw dependency text. |
|---|
502 | Stable error response with no raw dependency text. |
|---|
503 | Stable error response with no raw dependency text. |
|---|
504 | Stable error response with no raw dependency text. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/analytics/site-realtime
Read finalized realtime facts for the authenticated tenant
- operationId
getTenantSiteRealtime- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Tenant scope is derived exclusively from the authenticated identity. tenant_id is rejected. With query_version=2 the exact minute-aligned [from,to) interval is not rounded; without it, legacy hour alignment and original response keys apply. Missing or unfinalized evidence for any enclosing full UTC hour fails closed; zero traffic is returned only with complete source coverage.
参数
getTenantSiteRealtime 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
from | query | string(date-time) | 是 | Inclusive RFC3339 instant, exactly minute aligned after UTC normalization with query_version=2, otherwise hour aligned; never silently rounded. |
|---|
to | query | string(date-time) | 是 | Exclusive RFC3339 instant, exactly minute aligned after UTC normalization with query_version=2, otherwise hour aligned; later than from and no more than 31 days apart. |
|---|
query_version | query | integer: 2 / 3 / 4 | 否 | Explicit opt-in to minute queries and extended series/evidence. 3 adds coverage fields and returns settled hours when other enclosing hours are not finalized yet (coverage_complete=false, missing_windows lists the excluded hour starts) instead of 503. 4 is the realtime monitor: it reads every fact ingested so far, the unsettled current hour included, with no settlement reconciliation (coverage_complete=true, expected_events=0, finalized_through and source_watermark at the Unix epoch); it is a display read and never feeds billing. Omit for the legacy hour-aligned response; other values, empty or repeated values are rejected. |
|---|
site_id | query | string(uuid) | 否 | — |
|---|
host | query | string | 否 | One or more canonical lowercase hosts without trailing dots, separated by single spaces. |
|---|
listen_port | query | integer | 否 | Exact production listen port. Omit to include legacy port-zero facts. |
|---|
响应
getTenantSiteRealtime 响应| 状态码 | 说明 |
|---|
200 | Finalized atomic site realtime facts and source reconciliation evidence. |
|---|
400 | analytics_invalid_request |
|---|
401 | analytics_authentication_required |
|---|
403 | analytics_permission_denied or analytics_scope_forbidden |
|---|
408 | analytics_request_cancelled |
|---|
502 | analytics_storage_rejected, analytics_storage_invalid_response, or analytics_response_too_large |
|---|
503 | analytics_storage_unavailable or analytics_realtime_evidence_unavailable; no zero-value data is substituted. site-realtime with query_version=3 returns partial coverage instead of analytics_realtime_evidence_unavailable for unsettled hours; dependency failures remain 503. |
|---|
504 | analytics_query_timeout |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/analytics/summary
Read the authenticated tenant analytics summary
- operationId
getTenantAnalyticsSummary- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Requires a tenant-scoped identity with sites.read. Scope comes only from the authenticated identity; tenant_id is not accepted, even when it names that same tenant.
参数
getTenantAnalyticsSummary 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
from | query | string(date-time) | 是 | RFC3339 instant. After UTC normalization it must be hour aligned and earlier than to. |
|---|
to | query | string(date-time) | 是 | Exclusive RFC3339 instant. It must be hour aligned after UTC normalization; the window is at most 31 days. |
|---|
site_id | query | string(uuid) | 否 | — |
|---|
node_id | query | string(uuid) | 否 | — |
|---|
响应
getTenantAnalyticsSummary 响应| 状态码 | 说明 |
|---|
200 | Aggregated metrics for the normalized UTC window. 字段：data: AnalyticsSummaryMetrics meta: AnalyticsQueryMetadata |
|---|
400 | analytics_invalid_request |
|---|
401 | analytics_authentication_required |
|---|
403 | analytics_permission_denied or analytics_scope_forbidden |
|---|
408 | analytics_request_cancelled |
|---|
500 | analytics_internal_error |
|---|
502 | analytics_storage_rejected, analytics_storage_invalid_response, or analytics_response_too_large |
|---|
503 | analytics_storage_unavailable; no zero-value data is substituted. |
|---|
504 | analytics_query_timeout |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/analytics/top/{dimension}
Page through the authenticated tenant ranking
- operationId
getTenantAnalyticsTop- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Requires a tenant-scoped identity with sites.read. Scope comes only from the authenticated identity. The cursor is bound to scope, filters, dimension, and one ingestion snapshot. The ja4 dimension is reserved but unsupported in v1.
参数
getTenantAnalyticsTop 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
dimension | path | string: url / ip / domain / region / carrier / ja4 / referer / province / browser / os | 是 | region is the ISO country code, province the GB/T 2260 province code (both from the control plane's IP library at ingest), browser and os the node's User-Agent families. Empty values are returned as __unknown__. ip, domain, region, carrier, province, browser and os rank from the hourly history facts; url, ja4 and referer from the access log (see page.source and page.retained_from). |
|---|
from | query | string(date-time) | 是 | RFC3339 instant. After UTC normalization it must be hour aligned and earlier than to. |
|---|
to | query | string(date-time) | 是 | Exclusive RFC3339 instant. It must be hour aligned after UTC normalization; the window is at most 31 days. |
|---|
site_id | query | string(uuid) | 否 | — |
|---|
node_id | query | string(uuid) | 否 | — |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | Opaque cursor bound to the authenticated scope, filters, dimension, and snapshot. |
|---|
响应
getTenantAnalyticsTop 响应| 状态码 | 说明 |
|---|
200 | Deterministically ordered ranking page from one ingestion snapshot. 字段：data: array<AnalyticsRankItem> dimension: string: url / ip / domain / region / carrier / ja4 / referer / province / browser / os page: AnalyticsRankPage meta: AnalyticsQueryMetadata |
|---|
400 | analytics_invalid_request |
|---|
401 | analytics_authentication_required |
|---|
403 | analytics_permission_denied or analytics_scope_forbidden |
|---|
408 | analytics_request_cancelled |
|---|
422 | analytics_dimension_unsupported |
|---|
500 | analytics_internal_error |
|---|
502 | analytics_storage_rejected, analytics_storage_invalid_response, or analytics_response_too_large |
|---|
503 | analytics_storage_unavailable; no zero-value data is substituted. |
|---|
504 | analytics_query_timeout |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表