接口详情
Count distinct client IPs blocked by the global firewall or CC auto-bans
- operationId
getPlatformAnalyticsBlockedIPCount- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Requires a platform-scoped identity with sites.read or platform.admin. 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.
参数
getPlatformAnalyticsBlockedIPCount 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
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. |
|---|
tenant_id | query | string(uuid) | 否 | Platform route only. Omit for all tenants. |
|---|
site_id | query | string(uuid) | 否 | — |
|---|
node_id | query | string(uuid) | 否 | — |
|---|
响应
getPlatformAnalyticsBlockedIPCount 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表
Read the hourly distinct client IPs blocked by the global firewall
- operationId
getPlatformAnalyticsBlockedIPTrend- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Requires a platform-scoped identity with sites.read or platform.admin. Each returned UTC bucket contains the distinct client_ip count from global_firewall block events, bounded by one ingestion snapshot.
参数
getPlatformAnalyticsBlockedIPTrend 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
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. |
|---|
tenant_id | query | string(uuid) | 否 | Platform route only. Omit for all tenants. |
|---|
site_id | query | string(uuid) | 否 | — |
|---|
node_id | query | string(uuid) | 否 | — |
|---|
响应
getPlatformAnalyticsBlockedIPTrend 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表
List durable analytics connections dead-letter receipts
- operationId
listPlatformAnalyticsConnectionsDeadLetters- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read platform.admin
说明（契约原文）
Requires a revocable platform Bearer session with sites.read and platform.admin. An optional tenant_id narrows the digest-only durable receipt projection to one tenant. Raw payloads are never returned.
参数
listPlatformAnalyticsConnectionsDeadLetters 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
tenant_id | query | string(uuid) | 否 | Optional platform scope narrowing to one canonical tenant UUID. |
|---|
limit | query | integer | 否 | — |
|---|
after_sequence | query | integer(uint64) | 否 | Exclusive decimal JetStream dead-letter stream sequence cursor. |
|---|
响应
listPlatformAnalyticsConnectionsDeadLetters 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表
Read one durable analytics connections dead-letter receipt
- operationId
getPlatformAnalyticsConnectionsDeadLetter- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read platform.admin
说明（契约原文）
Requires a revocable platform Bearer session with sites.read and platform.admin. The response is a digest-only durable receipt and never includes raw payload or secret fields.
参数
getPlatformAnalyticsConnectionsDeadLetter 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
dead_letter_id | path | string | 是 | — |
|---|
响应
getPlatformAnalyticsConnectionsDeadLetter 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表
Read finalized connections retention facts for a tenant subscription
- operationId
getPlatformAnalyticsConnectionsRetention- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read platform.admin
说明（契约原文）
Requires a revocable platform Bearer session with sites.read and platform.admin. Tenant and subscription scope are mandatory and every returned fact is finalized, evidence-bound, and ordered by UTC period.
参数
getPlatformAnalyticsConnectionsRetention 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
tenant_id | query | string(uuid) | 是 | Exact tenant scope for the platform retention route. |
|---|
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 | 否 | — |
|---|
响应
getPlatformAnalyticsConnectionsRetention 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表
Read a platform or explicitly selected tenant hourly trend
- operationId
getPlatformAnalyticsHourlyTrend- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Requires a platform-scoped identity with sites.read or platform.admin. Buckets are UTC hours and only buckets containing events are returned.
参数
getPlatformAnalyticsHourlyTrend 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
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. |
|---|
tenant_id | query | string(uuid) | 否 | Platform route only. Omit for all tenants; tenant routes reject this parameter. |
|---|
site_id | query | string(uuid) | 否 | — |
|---|
node_id | query | string(uuid) | 否 | — |
|---|
响应
getPlatformAnalyticsHourlyTrend 响应| 状态码 | 说明 |
|---|
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/admin/analytics/l4-realtime
- operationId
getAdminL4Realtime- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
参数
getAdminL4Realtime 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
tenant_id | query | string(uuid) | 否 | 可选租户范围；省略时平台管理员查询全部租户 |
|---|
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 | 否 | — |
|---|
响应
getAdminL4Realtime 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表
List access logs for one explicitly selected tenant
- operationId
listPlatformAccessLogs- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Requires a platform-scoped identity. tenant_id is mandatory; this API never performs an all-tenant log query. URI output contains only an origin-form path and omits query and fragment content.
参数
listPlatformAccessLogs 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
tenant_id | query | string(uuid) | 否 | Platform route only; omit for all tenants or provide one tenant UUID to narrow the read. |
|---|
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. |
|---|
响应
listPlatformAccessLogs 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表
List durable access-log exports owned by the calling account for the target tenant
- operationId
listPlatformAccessLogExports- 认证
- 登录会话：主控登录后的 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.
参数
listPlatformAccessLogExports 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
tenant_id | query | string(uuid) | 是 | Platform route only; all-tenant log queries are forbidden. |
|---|
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) | 否 | — |
|---|
响应
listPlatformAccessLogExports 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表
Create a snapshot-bound access-log export for one target tenant
- operationId
createPlatformAccessLogExport- 认证
- 登录会话：主控登录后的 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.
参数
createPlatformAccessLogExport 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
tenant_id | query | string(uuid) | 是 | Platform route only; all-tenant log queries are forbidden. |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
createPlatformAccessLogExport 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
filter | AccessExportFilter | 是 | — |
|---|
响应
createPlatformAccessLogExport 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表
- operationId
getPlatformAccessLogExport- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
参数
getPlatformAccessLogExport 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
tenant_id | query | string(uuid) | 是 | Platform route only; all-tenant log queries are forbidden. |
|---|
export_id | path | string(uuid) | 是 | — |
|---|
响应
getPlatformAccessLogExport 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表
- operationId
downloadPlatformAccessLogExport- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
参数
downloadPlatformAccessLogExport 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
tenant_id | query | string(uuid) | 是 | Platform route only; all-tenant log queries are forbidden. |
|---|
export_id | path | string(uuid) | 是 | — |
|---|
X-Analytics-Download-Token | header | string | 是 | Short-lived one-time token. The server stores only its SHA-256 digest. |
|---|
响应
downloadPlatformAccessLogExport 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表
- operationId
grantPlatformAccessLogExportDownload- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Returns a short-lived one-time token bound to the current platform session, target tenant and export. Any session of the owning account may request a grant; a token from another session is rejected. Only its SHA-256 digest is stored.
参数
grantPlatformAccessLogExportDownload 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
tenant_id | query | string(uuid) | 是 | Platform route only; all-tenant log queries are forbidden. |
|---|
export_id | path | string(uuid) | 是 | — |
|---|
响应
grantPlatformAccessLogExportDownload 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表
List security block events for one explicitly selected tenant
- operationId
listPlatformBlockEvents- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Requires a platform-scoped identity and an explicit tenant_id. Returns the current security-event projection with the same snapshot-bounded opaque cursor contract as access logs. This is raw event retrieval, not an immutable block-state transition history.
参数
listPlatformBlockEvents 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
tenant_id | query | string(uuid) | 否 | Platform route only; omit for all tenants or provide one tenant UUID to narrow the read. |
|---|
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. |
|---|
响应
listPlatformBlockEvents 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表
List current ACL blocks across the customer control plane
- operationId
listPlatformCurrentBlocks- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Returns only CIDRs present in the active site ACL policy. A newer unpublished policy revision or open activation makes the item non-unlockable. tenant_id optionally narrows the platform-wide read; every row carries its tenant_id so write actions stay explicitly scoped.
参数
listPlatformCurrentBlocks 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
tenant_id | query | string(uuid) | 否 | Platform route only; omit for all tenants or provide one tenant UUID to narrow the read. |
|---|
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. |
|---|
响应
listPlatformCurrentBlocks 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表
Count current ACL blocks by site across the customer control plane
- operationId
countPlatformCurrentBlocksBySite- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
参数
countPlatformCurrentBlocksBySite 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
tenant_id | query | string(uuid) | 否 | Platform route only; omit for all tenants or provide one tenant UUID to narrow the read. |
|---|
响应
countPlatformCurrentBlocksBySite 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表
Unlock one current ACL block for an explicitly selected tenant
- operationId
unlockPlatformCurrentBlock- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.manage
说明（契约原文）
Removes exactly one CIDR from a new ACL policy revision, then starts a version-fenced edge activation. A stale active revision, open activation, missing target CIDR, or missing target-node snapshot fails closed with 409. Reusing the same key and body returns the same durable result; a conflicting body is rejected.
参数
unlockPlatformCurrentBlock 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
block_id | path | string(uuid) | 是 | Stable identity derived from site, active ACL policy and canonical CIDR. |
|---|
tenant_id | query | string(uuid) | 是 | Platform route only; all-tenant log queries are forbidden. |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
unlockPlatformCurrentBlock 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
reason_code | string | 是 | — |
|---|
响应
unlockPlatformCurrentBlock 响应| 状态码 | 说明 |
|---|
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/admin/analytics/logs/blocks/history
List audited unlock history across the customer control plane
- operationId
listPlatformBlockHistory- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Returns append-only cidr_unlock activation audit facts and their latest durable edge rollout progress. tenant_id optionally narrows the platform-wide read.
参数
listPlatformBlockHistory 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
tenant_id | query | string(uuid) | 否 | Platform route only; omit for all tenants or provide one tenant UUID to narrow the read. |
|---|
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. |
|---|
响应
listPlatformBlockHistory 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表
List cross-node CC coordination states of every tenant, optionally narrowed to one tenant or site
- operationId
listPlatformCCCoordinationStates- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
参数
listPlatformCCCoordinationStates 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
tenant_id | query | string(uuid) | 否 | Platform route only; omit for all tenants or provide one tenant UUID to narrow the read. |
|---|
site_id | query | string(uuid) | 否 | — |
|---|
limit | query | integer | 否 | Maximum current or historical block facts returned. |
|---|
响应
listPlatformCCCoordinationStates 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表
Release one exact cross-node CC state after a false-positive decision
- operationId
releasePlatformCCCoordinationState- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.manage
参数
releasePlatformCCCoordinationState 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
state_id | path | string(uuid) | 是 | — |
|---|
tenant_id | query | string(uuid) | 是 | Platform route only; all-tenant log queries are forbidden. |
|---|
site_id | query | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
X-Request-ID | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
releasePlatformCCCoordinationState 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
reason_code | string | 是 | — |
|---|
expected_generation | integer(int64) | 是 | — |
|---|
响应
releasePlatformCCCoordinationState 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表
Reconcile one tenant log fact against a verified GeoIP catalog
- operationId
getPlatformAnalyticsGeoEvidence- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
参数
getPlatformAnalyticsGeoEvidence 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
kind | path | string: access / block | 是 | — |
|---|
event_id | path | string | 是 | — |
|---|
from | query | string(date-time) | 是 | — |
|---|
to | query | string(date-time) | 是 | — |
|---|
tenant_id | query | string(uuid) | 是 | — |
|---|
site_id | query | string(uuid) | 是 | — |
|---|
node_id | query | string(uuid) | 是 | — |
|---|
client_ip | query | string(ip) | 是 | — |
|---|
database_version | query | string | 否 | — |
|---|
响应
getPlatformAnalyticsGeoEvidence 响应| 状态码 | 说明 |
|---|
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/admin/analytics/market-security
List relayed market supply attack log lines of any tenant
- operationId
listAdminMarketSecurityLogs- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：platform.admin
参数
listAdminMarketSecurityLogs 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
tenant_id | query | string(uuid) | 是 | — |
|---|
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 | 否 | — |
|---|
响应
listAdminMarketSecurityLogs 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表
Read one tenant's site monitoring as a platform administrator
- operationId
getPlatformSiteMonitoring- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：platform.admin
说明（契约原文）
Requires a platform session with platform.admin and exactly one canonical tenant_id. Omitting, duplicating, or changing tenant scope through identity headers is rejected before any source is queried.
参数
getPlatformSiteMonitoring 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
tenant_id | query | string(uuid) | 是 | — |
|---|
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 | 否 | — |
|---|
响应
getPlatformSiteMonitoring 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表
Read one tenant's quality diagnostics from the platform scope
- operationId
getPlatformQualityDiagnostics- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：platform.admin
参数
getPlatformQualityDiagnostics 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
tenant_id | query | string(uuid) | 是 | — |
|---|
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 | 否 | — |
|---|
响应
getPlatformQualityDiagnostics 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表
Read platform-wide or one tenant's finalized site realtime facts
- operationId
getPlatformSiteRealtime- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Requires a platform identity with sites.read or platform.admin. Omitting tenant_id queries all tenants; providing it narrows the query to one tenant. With query_version=2 the exact minute-aligned [from,to) interval is projected without rounding. Without query_version, legacy hour alignment and the original response keys are preserved. Its enclosing complete UTC hours must first have independent PostgreSQL source coverage; their expected counts are reconciled with a single ClickHouse access scan shared by all exact-range projections.
参数
getPlatformSiteRealtime 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
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. |
|---|
tenant_id | query | string(uuid) | 否 | Platform route only. Omit for all tenants or provide one exact tenant scope. |
|---|
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. |
|---|
响应
getPlatformSiteRealtime 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表
Read a platform or explicitly selected tenant analytics summary
- operationId
getPlatformAnalyticsSummary- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Requires a platform-scoped identity with sites.read or platform.admin. Omitting tenant_id queries all tenants; providing tenant_id narrows the query to that tenant. The time window is left-closed and right-open.
参数
getPlatformAnalyticsSummary 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
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. |
|---|
tenant_id | query | string(uuid) | 否 | Platform route only. Omit for all tenants; tenant routes reject this parameter. |
|---|
site_id | query | string(uuid) | 否 | — |
|---|
node_id | query | string(uuid) | 否 | — |
|---|
响应
getPlatformAnalyticsSummary 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表
Page through a platform or explicitly selected tenant ranking
- operationId
getPlatformAnalyticsTop- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：sites.read
说明（契约原文）
Requires a platform-scoped identity with sites.read or platform.admin. The cursor is bound to scope, filters, dimension, and one ingestion snapshot. The ja4 dimension is reserved but unsupported in v1.
参数
getPlatformAnalyticsTop 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
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. |
|---|
tenant_id | query | string(uuid) | 否 | Platform route only. Omit for all tenants; tenant routes reject this parameter. |
|---|
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. |
|---|
响应
getPlatformAnalyticsTop 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表