All Products
Search
Document Center

CDN:DescribeDomainUsageData

Last Updated:Oct 10, 2026

Queries the usage data of domain names in a specific billing region.

Operation description

  • Call frequency per user: 10 calls per second.

  • Supported time granularity: Depending on the maximum time span of a single query, the Interval request parameter supports different time granularities for queried data. The corresponding time range of queryable historical data and data latency are as follows:

Time granularityMaximum time span of a single queryQueryable historical data time rangeData latency
5 minutes3 days93 days15 minutes
1 hour7 days186 daysGenerally 3 to 4 hours
1 day31 days366 daysGenerally 4 hours, up to 24 hours

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

  • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

  • API: The API that you can call to perform the action.

  • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

  • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

    • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

    • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

  • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

  • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

cdn:DescribeDomainUsageData

none

*Domain

acs:cdn:*:{#accountId}:domain/{#DomainName}

None None

Request parameters

Parameter

Type

Required

Description

Example

DomainName

string

No

The accelerated domain name to query. You can specify multiple domain names separated by commas (,). A maximum of 100 domain names can be specified in a single query.

Note

If this parameter is left empty, the merged data of all accelerated domain names under the account is returned by default.

example.com

StartTime

string

Yes

The start time of the data to query.

Specify the time in the ISO 8601 standard in UTC. The format is yyyy-MM-ddTHH:mm:ssZ.

Note

The time granularity of the queried data is 5 minutes.

2015-12-10T20:00:00Z

EndTime

string

Yes

The end time of the data to query.

Specify the time in the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time must be in UTC.

Note

The end time must be later than the start time, and the time span cannot exceed 31 days.

2015-12-10T22:00:00Z

Field

string

Yes

The data type to query. Valid values:

  • bps: bandwidth.

  • traf: traffic.

  • acc: number of requests.

Note

acc does not support queries based on the Area parameter.

bps

Type

string

No

The type of usage data to query. Valid values:

  • static: static content.

  • dynamic: dynamic content.

  • all (default): all types.

static

DataProtocol

string

No

The protocol of the data to query. Valid values:

  • http: HTTP.

  • https: HTTPS.

  • quic: QUIC.

  • all (default): all the preceding protocols.

all

Area

string

No

The region code. Valid values:

  • CN (default): the Chinese mainland.

  • OverSeas: global (excluding the Chinese mainland).

  • AP1: Asia Pacific 1.

  • AP2: Asia Pacific 2.

  • AP3: Asia Pacific 3.

  • NA: North America.

  • SA: South America.

  • EU: Europe.

  • MEAA: Middle East and Africa.

  • all: all the preceding regions.

CN

Interval

string

No

The time granularity of the data to query, in seconds. Valid values: 300 (5 minutes), 3600 (1 hour), and 86400 (1 day).

  • Interval=300: You can query data within the last six months. The maximum time range of a single query is 3 days.

  • Interval=3600 or 86400: You can query data within the last year.

  • If Interval is not specified: The maximum time range of a single query is 1 month. If the query time range is 1 to 3 days, data is returned at an hourly granularity. If the query time range is 4 days or more, data is returned at a daily granularity.

300

ServiceType

string

No

Parameter combinations

The following table describes the mappings between billing data and parameter values. For more information about how to call the operation, see the sample requests.

Billing dataDataProtocolTypeFieldArea
Trafficall or not specifiedall or not specifiedtrafCN, OverSeas, AP1, AP2, AP3, NA, SA, EU, MEAA
Bandwidthall or not specifiedall or not specifiedbpsCN, OverSeas, AP1, AP2, AP3, NA, SA, EU, MEAA
HTTPS request for static contenthttpsstaticaccall
HTTP requests for dynamic contenthttpdynamicaccall
HTTPS requests for dynamic contenthttpsdynamicaccall
QUIC request for dynamic content (resources)quicdynamicaccall
QUIC request for static content (resources)quicstaticaccall

Response elements

Element

Type

Description

Example

object

The list of parameters.

RequestId

string

The request ID.

B955107D-E658-4E77-B913-E0AC3D31693E

DomainName

string

The accelerated domain name.

example.com

StartTime

string

The start time. The time is displayed in the ISO 8601 standard in UTC.

2015-12-10T20:00:00Z

EndTime

string

The end time. The time is displayed in the ISO 8601 standard in UTC.

2015-12-10T22:00:00Z

Type

string

The usage type.

bps

Area

string

The usage region.

CN

DataInterval

string

The time interval of each record, in seconds.

300

UsageDataPerInterval

object

DataModule

array<object>

The usage data for each time interval.

object

The usage data for each time interval.

Value

string

The usage value.

423304182

TimeStamp

string

The start time of the time slice.

Note

Multiple TimeStamp values returned in the data are called time slices. The time is displayed in the ISO 8601 standard in UTC.

2015-12-10T21:30:00Z

PeakTime

string

The time when the peak bandwidth is reached if Field is set to bps. Otherwise, the value is the same as TimeStamp.

2015-12-10T21:30:00Z

SpecialValue

string

The special usage.

Note

This parameter is used to mark the usage value in special cases. You can ignore this parameter if no special billing is involved.

423304182

Examples

Success response

JSON format

{
  "RequestId": "B955107D-E658-4E77-B913-E0AC3D31693E",
  "DomainName": "example.com",
  "StartTime": "2015-12-10T20:00:00Z",
  "EndTime": "2015-12-10T22:00:00Z",
  "Type": "bps",
  "Area": "CN",
  "DataInterval": "300",
  "UsageDataPerInterval": {
    "DataModule": [
      {
        "Value": "423304182",
        "TimeStamp": "2015-12-10T21:30:00Z",
        "PeakTime": "2015-12-10T21:30:00Z",
        "SpecialValue": "423304182"
      }
    ]
  }
}

Error codes

HTTP status code

Error code

Error message

Description

400 InvalidParameter The specified parameter is invalid. An exception occurred while deleting the live streaming region.
400 InvalidParameterType The specified Type is invalid. The Type parameter is set to an invalid value.
400 InvalidParameterField The specified Field is invalid. The Field parameter is set to an invalid value.
400 InvalidParameterStartTime The parameter StartTime is invalid. The specified StartTime parameter is invalid.
400 InvalidParameterEndTime The parameter EndTime is invalid. The EndTime parameter is invalid.
400 InvalidEndTime.Mismatch Specified EndTime does not match the specified StartTime. StartTime must be earlier than EndTime.
400 InvalidIntervalParameter The specified Interval is invalid. The specified time interval is invalid.
400 InvalidTimeSpan The time span exceeds the limit. The time span exceeds the limit. Configure a valid time span as described in API documentation.
400 InvalidStartTime.ValueNotSupported The specified value of parameter StartTime is not supported.
400 InvalidTime.Malformed Specified StartTime or EndTime is malformed. The specified start or end time is invalid.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.