Queries the resource usage data of specific domain names in a specified billable region.

Usage notes

The maximum number of times that each user can call this operation per second is 10.

The time granularity supported by the Interval parameter, the maximum time period within which historical data is available, and the data delay vary with the time range to query, as described in the following table.

Time granularity

Time range to query

Historical data available

Data delay

5 minutes

3 days

93 days

15 minutes

1 hour

31 days

186 days

4 hours

1 day

366 days

366 days

04:00 on the next day

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes DescribeDomainUsageData

The operation that you want to perform. Set this parameter to DescribeDomainUsageData.

EndTime String Yes 2015-12-10T22:00:00Z

The end of the time range 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. The maximum time range that can be queried is 31 days.
Field String Yes bps

The type of data to be queried. Valid values:

  • bps: bandwidth
  • traf: network traffic
  • acc: requests
Note acc does not support the Area parameter.
StartTime String Yes 2015-12-10T20:00:00Z

The beginning of the time range 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 data is collected every 5 minutes.
Type String No static

The type of content based on which the data is queried. Valid values:

  • static: static content
  • dynamic: dynamic content
  • all (default): both static and dynamic content
DataProtocol String No all

The protocol by which the data is queried. Valid values:

  • http: HTTP
  • https: HTTPS
  • quic: QUIC
  • all (default): HTTP, HTTPS, and QUIC
DomainName String No example.com

The accelerated domain name. You can query the resource usage data for a maximum of 100 domain names in each call. Separate domain names with commas (,).

Note If you do not set this parameter, the usage data of all accelerated domain names within your Alibaba Cloud account is returned.
Area String No CN

The ID of the billable region. Valid values:

  • CN (default): the Chinese mainland
  • OverSeas: outside 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 billable regions
Note For more information about billable regions, see Billable regions.
Interval String No 300

The time interval between the data entries. Unit: seconds.

The time granularity varies with the time range to query. Supported values: 300 (5 minutes), 3600 (1 hour), and 86400 (1 day). For more information, see Usage notes.

Billable items and parameters

The following table describes the parameters of each billable item. For more information about how to call relevant operations, see the sample requests.

Billable item

Valid value of DataProtocol

Valid value of Type

Valid value of Field

Valid value of Area

Data transfer

all or no value

all or no value

traf

CN, OverSeas, AP1, AP2, AP3, NA, SA, EU, and MEAA.

Bandwidth

all or no value

all or no value

bps

CN, OverSeas, AP1, AP2, AP3, NA, SA, EU, and MEAA.

HTTPS requests for static content

https

static

acc

all

HTTP requests for dynamic content

http

dynamic

acc

all

HTTPS requests for dynamic content

https

dynamic

acc

all

QUIC requests for dynamic content

quic

dynamic

acc

all

QUIC requests for static content

quic

static

acc

all

Response parameters

Parameter Type Example Description
Area String CN

The billable region where the usage information was collected.

DataInterval String 300

The time interval between the data entries. Unit: seconds.

DomainName String example.com

The accelerated domain name.

EndTime String 2015-12-10T22:00:00Z

The end of the time range that was queried.

RequestId String B955107D-E658-4E77-B913-E0AC3D31693E

The ID of the request.

StartTime String 2015-12-10T20:00:00Z

The beginning of the time range that was queried.

Type String static

The type of content based on which the usage information was collected.

UsageDataPerInterval Array of DataModule

The network traffic that was collected at each interval.

DataModule
PeakTime String 2015-12-10T21:30:00Z

If the Field parameter in the request is set to bps, this parameter returns the time of the peak bandwidth value. Otherwise, this parameter returns the same value as the TimeStamp parameter.

SpecialValue String 423304182

The data usage in a specific scenario.

Note Indicates the data usage in a specific scenario. If no special billable item is specified, ignore this parameter.
TimeStamp String 2015-12-10T21:30:00Z

The timestamp of the data returned.

Note The TimeStamp parameter may return multiple values.
Value String 423304182

The usage.

Note Usage data includes network traffic (measured in bytes), bandwidth values (measured in bits/s), and the number of requests.

Examples

Sample requests

// Queries data transfer in the Chinese mainland
http(s)://cdn.aliyuncs.com/?Action=DescribeDomainUsageData
&DomainName=example.com
&StartTime=2015-12-10T20:00:00Z
&EndTime=2015-12-10T22:00:00Z
&Field=traf
&Area=CN
&<Common request parameters>

// Queries bandwidth usage in Europe.
http(s)://cdn.aliyuncs.com/?Action=DescribeDomainUsageData
&DomainName=example.com
&StartTime=2015-12-10T20:00:00Z
&EndTime=2015-12-10T22:00:00Z
&Field=bps
&Area=EU
&<Common request parameters>

// Queries the number of HTTPS requests for static content.
http(s)://cdn.aliyuncs.com/?Action=DescribeDomainUsageData
&DomainName=example.com
&StartTime=2015-12-10T20:00:00Z
&EndTime=2015-12-10T22:00:00Z
&Type=static
&DataProtocol=https
&Field=acc
&Area=all
&<Common request parameters>

// Queries the number of HTTP requests for dynamic content.
http(s)://cdn.aliyuncs.com/?Action=DescribeDomainUsageData
&DomainName=example.com
&StartTime=2015-12-10T20:00:00Z
&EndTime=2015-12-10T22:00:00Z
&Type=dynamic
&DataProtocol=http
&Field=acc
&Area=all
&<Common request parameters>

// Queries the number of HTTPS requests for dynamic content.
http(s)://cdn.aliyuncs.com/?Action=DescribeDomainUsageData
&DomainName=example.com
&StartTime=2015-12-10T20:00:00Z
&EndTime=2015-12-10T22:00:00Z
&Type=dynamic
&DataProtocol=https
&Field=acc
&Area=all
&<Common request parameters>

// Queries the number of QUIC requests for dynamic content.
http(s)://cdn.aliyuncs.com?Action=DescribeDomainUsageData
&DomainName=example.com
&StartTime=2015-12-10T20:00:00Z
&EndTime=2015-12-10T22:00:00Z
&Type=dynamic
&DataProtocol=quic
&Field=acc
&Area=all
&<Common request parameters>

// Queries the number of QUIC requests for static content.
http(s)://cdn.aliyuncs.com?Action=DescribeDomainUsageData
&DomainName=example.com
&StartTime=2015-12-10T20:00:00Z
&EndTime=2015-12-10T22:00:00Z
&Type=static
&DataProtocol=quic
&Field=acc
&Area=all
&<Common request parameters>

Sample success responses

XML format 

<DescribeDomainUsageDataResponse>
  <DomainName>example.com</DomainName>
  <UsageDataPerInterval>
        <DataModule>
              <TimeStamp>2015-12-10T20:00:00Z</TimeStamp>
              <PeakTime>2015-12-10T20:05:00Z</PeakTime>
              <Value>423304182</Value>
              <SpecialValue>423304182</SpecialValue>
        </DataModule>
        <DataModule>
              <TimeStamp>2015-12-10T21:00:00Z</TimeStamp>
              <PeakTime>2015-12-10T21:30:00Z</PeakTime>
              <Value>454680793</Value>
              <SpecialValue>423304182</SpecialValue>
        </DataModule>
  </UsageDataPerInterval>
  <RequestId>B955107D-E658-4E77-B913-E0AC3D31693E</RequestId>
  <StartTime>2015-12-10T20:00Z</StartTime>
  <EndTime>2015-12-10T21:00Z</EndTime>
  <Area>CN</Area>
  <Type>traf</Type>
</DescribeDomainUsageDataResponse>

JSON format 

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

Error codes

HttpCode Error code Error message Description
400 InvalidTimeRange Invalid StartTime and EndTime range. The error message returned because the specified start time and end time are invalid.

For a list of error codes, visit the API Error Center.