cdnca

API reference

/v1/package-usage

2 operations

← All groups · First call? Read the tutorial: auth, permissions, requests and responses, common failures

MethodPathSummaryAuth
GET/v1/package-usage查询当前用户套餐用量Session
GET/v1/package-usage/search当前租户整体用量曲线（带宽/流量按时间桶聚合）Session

Contract file：api/control-package-usage.openapi.yaml

Operation details

GET /v1/package-usage

查询当前用户套餐用量

operationId
queryTenantPackageUsage
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

queryTenantPackageUsage Parameters
NameInTypeRequiredDescription
subscription_idquerystring(uuid)Yes—
site_idquerystring(uuid)No—
fromquerystring(date-time)Yes—
toquerystring(date-time)Yes—
timezonequerystringYes—
bucketquerystring: hour / dayYes—
limitqueryintegerNo—
cursorquerystringNo—

Responses

queryTenantPackageUsage Responses
StatusDescription
200使用冻结数据快照计算的套餐用量

Fields：metric_schema_version: string subscription_id: string(uuid) site_id?: string(uuid) from: string(date-time) to: string(date-time) timezone: string bucket: string: hour / day traffic_bytes: string http_traffic_bytes: string l4_traffic_bytes: string peak_bandwidth_bps: string bandwidth_95th_bps: string connections: string source_watermark: string finalized_through: string(date-time) delayed: boolean series: array<PackageUsagePoint> next_cursor?: string

400稳定错误信封
401稳定错误信封
403稳定错误信封
404稳定错误信封
408稳定错误信封
502稳定错误信封
503稳定错误信封

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/package-usage/search

当前租户整体用量曲线（带宽/流量按时间桶聚合）

operationId
searchTenantPackageUsage
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.

Description (from the contract)

仅 tenant 作用域且具有 package_subscriptions.read（或 platform.admin）权限；只统计调用者自己的租户作用域。 口径与 /v1/admin/package-usage/search 相同（access_metering_facts_v1 + l4_session_facts_v1，不新建账本）， 不接受 user_ids / subscription_ids（传入返回400）；service_type、domains、listen_ports 同管理员接口。

Parameters

searchTenantPackageUsage Parameters
NameInTypeRequiredDescription
fromquerystring(date-time)Yes—
toquerystring(date-time)Yes—
timezonequerystringYes—
bucketquerystring: hour / dayYes—
X-Request-IDheaderstringYes—
service_typequerystring: all / site / streamNo—
domainsquerystringNo—
listen_portsquerystringNo—

Responses

searchTenantPackageUsage Responses
StatusDescription
200有界结果；filters.user_ids 与 subscription_ids 恒为空数组。

Fields：schema: string from: string(date-time) to: string(date-time) timezone: string bucket: string: hour / day filters: UsageSearchFilters bandwidth_basis: string has_data: boolean traffic_bytes: string peak_bandwidth_bps: string bandwidth_95th_bps: string series: array<UsageSearchPoint>

400稳定错误信封
401稳定错误信封
403稳定错误信封
408稳定错误信封
502稳定错误信封
503稳定错误信封

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