Operation details
GET /v1/analytics/blocked-ip-count
Count distinct client IPs blocked by the global firewall or CC auto-bans
- operationId
getTenantAnalyticsBlockedIPCount- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：sites.read
Description (from the contract)
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.
Parameters
getTenantAnalyticsBlockedIPCount Parameters| Name | In | Type | Required | Description |
|---|
from | query | string(date-time) | Yes | RFC3339 instant. After UTC normalization it must be exactly hour aligned and earlier than to. |
|---|
to | query | string(date-time) | Yes | Exclusive RFC3339 instant. After UTC normalization it must be exactly hour aligned. The window may not exceed 31 days. |
|---|
site_id | query | string(uuid) | No | — |
|---|
node_id | query | string(uuid) | No | — |
|---|
Responses
getTenantAnalyticsBlockedIPCount Responses| Status | Description |
|---|
200 | Distinct client IPs blocked by global firewall events or auto-banned by CC rules in the normalized UTC window. Fields：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 |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/analytics/blocked-ip-trend
Read the hourly distinct client IPs blocked by the global firewall
- operationId
getTenantAnalyticsBlockedIPTrend- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：sites.read
Description (from the contract)
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.
Parameters
getTenantAnalyticsBlockedIPTrend Parameters| Name | In | Type | Required | Description |
|---|
from | query | string(date-time) | Yes | RFC3339 instant. After UTC normalization it must be exactly hour aligned and earlier than to. |
|---|
to | query | string(date-time) | Yes | Exclusive RFC3339 instant. After UTC normalization it must be exactly hour aligned. The window may not exceed 31 days. |
|---|
site_id | query | string(uuid) | No | — |
|---|
node_id | query | string(uuid) | No | — |
|---|
Responses
getTenantAnalyticsBlockedIPTrend Responses| Status | Description |
|---|
200 | Hourly distinct client IPs blocked by global firewall events. Fields：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 |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/analytics/connections/dead-letters
List durable analytics connections dead-letter receipts
- operationId
listTenantAnalyticsConnectionsDeadLetters- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：sites.read
Description (from the contract)
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.
Parameters
listTenantAnalyticsConnectionsDeadLetters Parameters| Name | In | Type | Required | Description |
|---|
limit | query | integer | No | — |
|---|
after_sequence | query | integer(uint64) | No | Exclusive decimal JetStream dead-letter stream sequence cursor. |
|---|
Responses
listTenantAnalyticsConnectionsDeadLetters Responses| Status | Description |
|---|
200 | Digest-only durable DLQ receipts ordered by dead-letter stream sequence. Fields：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. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/analytics/connections/dead-letters/{dead_letter_id}
Read one durable analytics connections dead-letter receipt
- operationId
getTenantAnalyticsConnectionsDeadLetter- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：sites.read
Description (from the contract)
Requires a revocable tenant Bearer session with sites.read. The tenant scope is derived exclusively from the session and raw payload is never returned.
Parameters
getTenantAnalyticsConnectionsDeadLetter Parameters| Name | In | Type | Required | Description |
|---|
dead_letter_id | path | string | Yes | — |
|---|
Responses
getTenantAnalyticsConnectionsDeadLetter Responses| Status | Description |
|---|
200 | One digest-only durable DLQ receipt. Fields：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. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/analytics/connections/retention
Read finalized connections retention facts for the authenticated tenant
- operationId
getTenantAnalyticsConnectionsRetention- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：sites.read
Description (from the contract)
Requires a revocable tenant Bearer session with sites.read. Tenant scope is derived exclusively from that session; tenant_id is rejected.
Parameters
getTenantAnalyticsConnectionsRetention Parameters| Name | In | Type | Required | Description |
|---|
subscription_id | query | string(uuid) | Yes | Package subscription authority captured at event time. |
|---|
from | query | string(date-time) | Yes | Inclusive canonical UTC RFC3339 instant. |
|---|
to | query | string(date-time) | Yes | Exclusive canonical UTC RFC3339 instant; the window may not exceed 31 days. |
|---|
limit | query | integer | No | — |
|---|
Responses
getTenantAnalyticsConnectionsRetention Responses| Status | Description |
|---|
200 | Finalized connections facts in ascending period order. Fields：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. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/analytics/hourly-trend
Read the authenticated tenant hourly trend
- operationId
getTenantAnalyticsHourlyTrend- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：sites.read
Description (from the contract)
Requires a tenant-scoped identity with sites.read. Buckets are UTC hours and only buckets containing events are returned.
Parameters
getTenantAnalyticsHourlyTrend Parameters| Name | In | Type | Required | Description |
|---|
from | query | string(date-time) | Yes | RFC3339 instant. After UTC normalization it must be hour aligned and earlier than to. |
|---|
to | query | string(date-time) | Yes | Exclusive RFC3339 instant. It must be hour aligned after UTC normalization; the window is at most 31 days. |
|---|
site_id | query | string(uuid) | No | — |
|---|
node_id | query | string(uuid) | No | — |
|---|
Responses
getTenantAnalyticsHourlyTrend Responses| Status | Description |
|---|
200 | UTC hourly metrics ordered by hour ascending; hours with no events are omitted. Fields：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 |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/analytics/l4-realtime
- operationId
getTenantL4Realtime- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Parameters
getTenantL4Realtime Parameters| Name | In | Type | Required | Description |
|---|
range | query | string: 1h / 6h / 12h / 24h / custom | Yes | — |
|---|
timezone | query | string | Yes | — |
|---|
from | query | string(date-time) | No | — |
|---|
to | query | string(date-time) | No | — |
|---|
site_id | query | string(uuid) | No | — |
|---|
stream_id | query | string(uuid) | No | — |
|---|
node_id | query | string(uuid) | No | — |
|---|
protocol | query | string: tcp / udp | No | — |
|---|
listen_port | query | integer | No | — |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | — |
|---|
Responses
getTenantL4Realtime Responses| Status | Description |
|---|
200 | L4 session aggregates Fields：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. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/analytics/logs/access
List access logs for the authenticated tenant
- operationId
listTenantAccessLogs- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：sites.read
Description (from the contract)
Scope comes only from the authenticated tenant identity. Supplying tenant_id, even with the same value, returns 403.
Parameters
listTenantAccessLogs Parameters| Name | In | Type | Required | Description |
|---|
from | query | string(date-time) | Yes | Inclusive RFC3339 instant with at most millisecond precision. It is normalized to UTC and must be earlier than to. |
|---|
to | query | string(date-time) | Yes | Exclusive RFC3339 instant with at most millisecond precision. The window may not exceed 31 days. |
|---|
site_id | query | string(uuid) | No | — |
|---|
host | query | string | No | Access logs and block events: one host or up to 64 distinct space-separated hosts. |
|---|
node_id | query | string(uuid) | No | — |
|---|
client_ip | query | string(ip) | No | Exact IPv4 or IPv6 address without a zone identifier. |
|---|
uri_path | query | string | No | Exact origin-form path after query and fragment removal. |
|---|
uri_path_match | query | string: exact / prefix | No | How uri_path matches; prefix uses a startsWith match on the origin-form path. Requires uri_path. |
|---|
status_code | query | integer | No | — |
|---|
method | query | string | No | Exact HTTP method; access-log routes only. |
|---|
protocol | query | string | No | Exact stored protocol; access-log routes only. |
|---|
cache_status | query | string | No | Exact stored cache status; access-log routes only. |
|---|
upstream_result | query | string | No | — |
|---|
content_type | query | string | No | — |
|---|
user_agent | query | string | No | — |
|---|
request_bytes_min | query | integer(uint64) | No | — |
|---|
request_bytes_max | query | integer(uint64) | No | — |
|---|
response_bytes_min | query | integer(uint64) | No | — |
|---|
response_bytes_max | query | integer(uint64) | No | — |
|---|
country_code | query | string | No | Exact stored country or region code. |
|---|
carrier | query | string | No | Exact stored carrier value. |
|---|
ja4 | query | string | No | Exact stored JA4 fingerprint. Rows without a source JA4 do not match. |
|---|
origin_connect_us_min | query | integer(uint64) | No | — |
|---|
origin_connect_us_max | query | integer(uint64) | No | — |
|---|
origin_first_byte_us_min | query | integer(uint64) | No | — |
|---|
origin_first_byte_us_max | query | integer(uint64) | No | — |
|---|
origin_total_us_min | query | integer(uint64) | No | — |
|---|
origin_total_us_max | query | integer(uint64) | No | — |
|---|
limit | query | integer | No | Page size. When more rows exist at the fixed snapshot, the response includes an opaque next_cursor. |
|---|
cursor | query | string | No | 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. |
|---|
Responses
listTenantAccessLogs Responses| Status | Description |
|---|
200 | Snapshot-bounded access-log page. Fields：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. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/analytics/logs/access/exports
List durable access-log exports owned by the calling tenant account
- operationId
listTenantAccessLogExports- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：sites.read
Description (from the contract)
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.
Parameters
listTenantAccessLogExports Parameters| Name | In | Type | Required | Description |
|---|
from | query | string(date-time) | No | Export scope lookup; when present, to is required and the filters follow the access-log list. |
|---|
to | query | string(date-time) | No | Export scope lookup; exclusive end of the window. |
|---|
site_id | query | string(uuid) | No | — |
|---|
host | query | string | No | Access logs and block events: one host or up to 64 distinct space-separated hosts. |
|---|
node_id | query | string(uuid) | No | — |
|---|
client_ip | query | string(ip) | No | Exact IPv4 or IPv6 address without a zone identifier. |
|---|
uri_path | query | string | No | Exact origin-form path after query and fragment removal. |
|---|
uri_path_match | query | string: exact / prefix | No | How uri_path matches; prefix uses a startsWith match on the origin-form path. Requires uri_path. |
|---|
status_code | query | integer | No | — |
|---|
method | query | string | No | Exact HTTP method; access-log routes only. |
|---|
protocol | query | string | No | Exact stored protocol; access-log routes only. |
|---|
cache_status | query | string | No | Exact stored cache status; access-log routes only. |
|---|
upstream_result | query | string | No | — |
|---|
content_type | query | string | No | — |
|---|
user_agent | query | string | No | — |
|---|
request_bytes_min | query | integer(uint64) | No | — |
|---|
request_bytes_max | query | integer(uint64) | No | — |
|---|
response_bytes_min | query | integer(uint64) | No | — |
|---|
response_bytes_max | query | integer(uint64) | No | — |
|---|
country_code | query | string | No | Exact stored country or region code. |
|---|
carrier | query | string | No | Exact stored carrier value. |
|---|
ja4 | query | string | No | Exact stored JA4 fingerprint. Rows without a source JA4 do not match. |
|---|
origin_connect_us_min | query | integer(uint64) | No | — |
|---|
origin_connect_us_max | query | integer(uint64) | No | — |
|---|
origin_first_byte_us_min | query | integer(uint64) | No | — |
|---|
origin_first_byte_us_max | query | integer(uint64) | No | — |
|---|
origin_total_us_min | query | integer(uint64) | No | — |
|---|
origin_total_us_max | query | integer(uint64) | No | — |
|---|
Responses
listTenantAccessLogExports Responses| Status | Description |
|---|
200 | At most 50 exports for the exact actor, session, scope and tenant. Fields：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. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/analytics/logs/access/exports
Create a snapshot-bound access-log export for the current tenant
- operationId
createTenantAccessLogExport- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：sites.read
Description (from the contract)
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.
Parameters
createTenantAccessLogExport Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
createTenantAccessLogExport Request body| Name | Type | Required | Description |
|---|
filter | AccessExportFilter | Yes | — |
|---|
Responses
createTenantAccessLogExport Responses| Status | Description |
|---|
202 | Durable export request accepted; an identical idempotency replay returns the same job. Fields：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. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/analytics/logs/access/exports/{export_id}
- operationId
getTenantAccessLogExport- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：sites.read
Parameters
getTenantAccessLogExport Parameters| Name | In | Type | Required | Description |
|---|
export_id | path | string(uuid) | Yes | — |
|---|
Responses
getTenantAccessLogExport Responses| Status | Description |
|---|
200 | Session-bound durable export status. Fields：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. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/analytics/logs/access/exports/{export_id}/download
- operationId
downloadTenantAccessLogExport- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：sites.read
Parameters
downloadTenantAccessLogExport Parameters| Name | In | Type | Required | Description |
|---|
export_id | path | string(uuid) | Yes | — |
|---|
X-Analytics-Download-Token | header | string | Yes | Short-lived one-time token. The server stores only its SHA-256 digest. |
|---|
Responses
downloadTenantAccessLogExport Responses| Status | Description |
|---|
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. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/analytics/logs/access/exports/{export_id}/download-grants
- operationId
grantTenantAccessLogExportDownload- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：sites.read
Description (from the contract)
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.
Parameters
grantTenantAccessLogExportDownload Parameters| Name | In | Type | Required | Description |
|---|
export_id | path | string(uuid) | Yes | — |
|---|
Responses
grantTenantAccessLogExportDownload Responses| Status | Description |
|---|
201 | One-time grant. Only the SHA-256 token digest is persisted. Fields：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. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/analytics/logs/block-events
List security block events for the authenticated tenant
- operationId
listTenantBlockEvents- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：sites.read
Description (from the contract)
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.
Parameters
listTenantBlockEvents Parameters| Name | In | Type | Required | Description |
|---|
from | query | string(date-time) | Yes | Inclusive RFC3339 instant with at most millisecond precision. It is normalized to UTC and must be earlier than to. |
|---|
to | query | string(date-time) | Yes | Exclusive RFC3339 instant with at most millisecond precision. The window may not exceed 31 days. |
|---|
site_id | query | string(uuid) | No | — |
|---|
node_id | query | string(uuid) | No | — |
|---|
client_ip | query | string(ip) | No | Exact IPv4 or IPv6 address without a zone identifier. |
|---|
uri_path | query | string | No | Exact origin-form path after query and fragment removal. |
|---|
uri_path_match | query | string: exact / prefix | No | How uri_path matches; prefix uses a startsWith match on the origin-form path. Requires uri_path. |
|---|
status_code | query | const 0 | integer | No | Exact stored status; 0 means no HTTP status was recorded. |
|---|
action | query | string: block / challenge / log / temporary_ban | No | 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 | No | Block events only: narrow to one event type (waf, cc, acl, ...). |
|---|
host | query | string | No | Access logs and block events: one host or up to 64 distinct space-separated hosts. |
|---|
country_code | query | string | No | Exact stored country or region code. |
|---|
carrier | query | string | No | Exact stored carrier value. |
|---|
ja4 | query | string | No | Exact stored JA4 fingerprint. Rows without a source JA4 do not match. |
|---|
origin_connect_us_min | query | integer(uint64) | No | — |
|---|
origin_connect_us_max | query | integer(uint64) | No | — |
|---|
origin_first_byte_us_min | query | integer(uint64) | No | — |
|---|
origin_first_byte_us_max | query | integer(uint64) | No | — |
|---|
origin_total_us_min | query | integer(uint64) | No | — |
|---|
origin_total_us_max | query | integer(uint64) | No | — |
|---|
limit | query | integer | No | Page size. When more rows exist at the fixed snapshot, the response includes an opaque next_cursor. |
|---|
cursor | query | string | No | 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. |
|---|
Responses
listTenantBlockEvents Responses| Status | Description |
|---|
200 | Snapshot-bounded security block-event page. Fields：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. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/analytics/logs/blocks/current
List current ACL blocks for the authenticated tenant
- operationId
listTenantCurrentBlocks- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：sites.read
Description (from the contract)
Scope comes only from the authenticated tenant identity. Supplying a tenant_id is rejected rather than re-scoping the request.
Parameters
listTenantCurrentBlocks Parameters| Name | In | Type | Required | Description |
|---|
site_id | query | string(uuid) | No | — |
|---|
limit | query | integer | No | Maximum current or historical block facts returned. |
|---|
offset | query | integer | No | Number of matching current or historical block facts to skip. |
|---|
Responses
listTenantCurrentBlocks Responses| Status | Description |
|---|
200 | Current active ACL block facts. Fields：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. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/analytics/logs/blocks/current-count
Count current ACL blocks by site for the authenticated tenant
- operationId
countTenantCurrentBlocksBySite- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：sites.read
Responses
countTenantCurrentBlocksBySite Responses| Status | Description |
|---|
200 | Current active ACL block totals grouped by site. Fields：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. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/analytics/logs/blocks/current/{block_id}/unlock
Unlock one current ACL block for the authenticated tenant
- operationId
unlockTenantCurrentBlock- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：security_policies.manage
Description (from the contract)
Uses only the authenticated tenant scope and the same policy revision, idempotency, activation and conflict contract as the platform route.
Parameters
unlockTenantCurrentBlock Parameters| Name | In | Type | Required | Description |
|---|
block_id | path | string(uuid) | Yes | Stable identity derived from site, active ACL policy and canonical CIDR. |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
unlockTenantCurrentBlock Request body| Name | Type | Required | Description |
|---|
reason_code | string | Yes | — |
|---|
Responses
unlockTenantCurrentBlock Responses| Status | Description |
|---|
202 | The successor policy and activation were durably accepted. Fields：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. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/analytics/logs/blocks/history
List audited unlock history for the authenticated tenant
- operationId
listTenantBlockHistory- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：sites.read
Description (from the contract)
Scope comes only from the authenticated tenant identity. Raw security events remain available from the separate block-events route.
Parameters
listTenantBlockHistory Parameters| Name | In | Type | Required | Description |
|---|
site_id | query | string(uuid) | No | — |
|---|
limit | query | integer | No | Maximum current or historical block facts returned. |
|---|
offset | query | integer | No | Number of matching current or historical block facts to skip. |
|---|
Responses
listTenantBlockHistory Responses| Status | Description |
|---|
200 | Append-only CIDR unlock history with durable edge progress. Fields：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. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/analytics/logs/cc-coordination
List cross-node CC coordination states of the authenticated tenant, optionally narrowed to one site
- operationId
listTenantCCCoordinationStates- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：sites.read
Parameters
listTenantCCCoordinationStates Parameters| Name | In | Type | Required | Description |
|---|
site_id | query | string(uuid) | No | — |
|---|
limit | query | integer | No | Maximum current or historical block facts returned. |
|---|
Responses
listTenantCCCoordinationStates Responses| Status | Description |
|---|
200 | Durable tenant/site-scoped cross-node CC state. Fields：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. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/analytics/logs/cc-coordination/{state_id}/release
Release one exact cross-node CC state for the authenticated tenant
- operationId
releaseTenantCCCoordinationState- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：security_policies.manage
Parameters
releaseTenantCCCoordinationState Parameters| Name | In | Type | Required | Description |
|---|
state_id | path | string(uuid) | Yes | — |
|---|
site_id | query | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
releaseTenantCCCoordinationState Request body| Name | Type | Required | Description |
|---|
reason_code | string | Yes | — |
|---|
expected_generation | integer(int64) | Yes | — |
|---|
Responses
releaseTenantCCCoordinationState Responses| Status | Description |
|---|
202 | The exact generation was accepted for audited release. Fields：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. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/analytics/logs/{kind}/geo-evidence/{event_id}
Reconcile one authenticated tenant log fact against a verified GeoIP catalog
- operationId
getTenantAnalyticsGeoEvidence- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：sites.read
Description (from the contract)
tenant_id is forbidden; the tenant comes only from authenticated identity. The raw address is never returned.
Parameters
getTenantAnalyticsGeoEvidence Parameters| Name | In | Type | Required | Description |
|---|
kind | path | string: access / block | Yes | — |
|---|
event_id | path | string | Yes | — |
|---|
from | query | string(date-time) | Yes | — |
|---|
to | query | string(date-time) | Yes | — |
|---|
site_id | query | string(uuid) | Yes | — |
|---|
node_id | query | string(uuid) | Yes | — |
|---|
client_ip | query | string(ip) | Yes | — |
|---|
database_version | query | string | No | — |
|---|
Responses
getTenantAnalyticsGeoEvidence Responses| Status | Description |
|---|
200 | Verified bounded geo evidence. Fields：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. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/analytics/market-security
List relayed market supply attack log lines of the session tenant
- operationId
listMarketSecurityLogs- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：sites.read
Parameters
listMarketSecurityLogs Parameters| Name | In | Type | Required | Description |
|---|
from | query | string(date-time) | Yes | RFC 3339; at most 31 days before to. |
|---|
to | query | string(date-time) | Yes | — |
|---|
site_id | query | string(uuid) | No | — |
|---|
client_ip | query | string | No | — |
|---|
host | query | string | No | — |
|---|
cursor | query | string | No | meta.next_cursor of the previous page. |
|---|
limit | query | integer | No | — |
|---|
Responses
listMarketSecurityLogs Responses| Status | Description |
|---|
200 | Newest first. Fields：data: array<Log> meta: object |
|---|
400 | Error. |
|---|
401 | Error. |
|---|
403 | Error. |
|---|
405 | Error. |
|---|
503 | Error. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/analytics/site-monitoring
Read site monitoring for the authenticated tenant
- operationId
getTenantSiteMonitoring- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：sites.read
Description (from the contract)
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.
Parameters
getTenantSiteMonitoring Parameters| Name | In | Type | Required | Description |
|---|
range | query | string: 1h / 6h / 12h / custom | Yes | 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) | No | Inclusive UTC boundary, required only for range=custom. |
|---|
to | query | string(date-time) | No | Exclusive UTC boundary, required only for range=custom. |
|---|
timezone | query | string | Yes | — |
|---|
site_id | query | string(uuid) | No | — |
|---|
node_id | query | string(uuid) | No | — |
|---|
domain | query | string | No | — |
|---|
listen_port | query | integer | No | — |
|---|
rank_by | query | string: host / site / node / status_code | No | — |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Opaque snapshot- and filter-bound cursor. |
|---|
X-Request-ID | header | string | No | — |
|---|
Responses
getTenantSiteMonitoring Responses| Status | Description |
|---|
200 | Finalized monitoring aggregate. Fields：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. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/analytics/site-quality-diagnostics
Read tenant quality diagnostics from finalized access facts
- operationId
getTenantQualityDiagnostics- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：sites.read
Parameters
getTenantQualityDiagnostics Parameters| Name | In | Type | Required | Description |
|---|
from | query | string(date-time) | Yes | Inclusive UTC millisecond boundary. |
|---|
to | query | string(date-time) | Yes | Exclusive UTC millisecond boundary, at most 31 days after from. |
|---|
site_id | query | string(uuid) | No | — |
|---|
node_id | query | string(uuid) | No | — |
|---|
category | query | string: upstream_5xx / edge_530 / no_host / config_mismatch | No | — |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | — |
|---|
Responses
getTenantQualityDiagnostics Responses| Status | Description |
|---|
200 | Finalized, latest-state diagnostics at one exact snapshot. Fields：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. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/analytics/site-realtime
Read finalized realtime facts for the authenticated tenant
- operationId
getTenantSiteRealtime- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：sites.read
Description (from the contract)
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.
Parameters
getTenantSiteRealtime Parameters| Name | In | Type | Required | Description |
|---|
from | query | string(date-time) | Yes | Inclusive RFC3339 instant, exactly minute aligned after UTC normalization with query_version=2, otherwise hour aligned; never silently rounded. |
|---|
to | query | string(date-time) | Yes | 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 | No | 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) | No | — |
|---|
host | query | string | No | One or more canonical lowercase hosts without trailing dots, separated by single spaces. |
|---|
listen_port | query | integer | No | Exact production listen port. Omit to include legacy port-zero facts. |
|---|
Responses
getTenantSiteRealtime Responses| Status | Description |
|---|
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 |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/analytics/summary
Read the authenticated tenant analytics summary
- operationId
getTenantAnalyticsSummary- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：sites.read
Description (from the contract)
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.
Parameters
getTenantAnalyticsSummary Parameters| Name | In | Type | Required | Description |
|---|
from | query | string(date-time) | Yes | RFC3339 instant. After UTC normalization it must be hour aligned and earlier than to. |
|---|
to | query | string(date-time) | Yes | Exclusive RFC3339 instant. It must be hour aligned after UTC normalization; the window is at most 31 days. |
|---|
site_id | query | string(uuid) | No | — |
|---|
node_id | query | string(uuid) | No | — |
|---|
Responses
getTenantAnalyticsSummary Responses| Status | Description |
|---|
200 | Aggregated metrics for the normalized UTC window. Fields：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 |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/analytics/top/{dimension}
Page through the authenticated tenant ranking
- operationId
getTenantAnalyticsTop- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：sites.read
Description (from the contract)
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.
Parameters
getTenantAnalyticsTop Parameters| Name | In | Type | Required | Description |
|---|
dimension | path | string: url / ip / domain / region / carrier / ja4 / referer / province / browser / os | Yes | 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) | Yes | RFC3339 instant. After UTC normalization it must be hour aligned and earlier than to. |
|---|
to | query | string(date-time) | Yes | Exclusive RFC3339 instant. It must be hour aligned after UTC normalization; the window is at most 31 days. |
|---|
site_id | query | string(uuid) | No | — |
|---|
node_id | query | string(uuid) | No | — |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Opaque cursor bound to the authenticated scope, filters, dimension, and snapshot. |
|---|
Responses
getTenantAnalyticsTop Responses| Status | Description |
|---|
200 | Deterministically ordered ranking page from one ingestion snapshot. Fields：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 |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list