tencent cloud

Feedback

ListTopData

Last updated: 2022-08-25 10:14:25

1. API Description

Domain name for API request: cdn.tencentcloudapi.com.

This API is used to list data sorted the following ways by using different combinations of the Metric and Filter input parameters:

  • It sorts access URLs by total traffic and total requests, and returns the top 1,000 URLs in descending order.
  • It sorts client districts by total traffic and total requests, and returns the list of districts in descending order.
  • It sorts client ISPs by total traffic and total requests, and returns the list of ISPs in descending order.
  • It sorts domain names by total traffic, peak bandwidth, total requests, average hit rate, and 2XX/3XX/4XX/5XX status codes, and returns the list of domain names in descending order.
  • It sorts domain names by total origin-pull traffic, peak origin-pull bandwidth, total origin-pull requests, average origin-pull failure rate, and 2XX/3XX/4XX/5XX origin-pull status codes, and returns the list of domain names in descending order.

Note: only data from the last 90 days will be queried.

A maximum of 20 requests can be initiated per second for this API.

We recommend you to use API Explorer
Try it
API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name Required Type Description
Action Yes String Common Params. The value used for this API: ListTopData.
Version Yes String Common Params. The value used for this API: 2018-06-06.
Region No String Common Params. This parameter is not required for this API.
StartTime Yes Timestamp Query start time in the format of yyyy-MM-dd HH:mm:ss
Only supports data query at daily granularity. The date in the input parameter is used as the start date.
If the specified start date is greater than 00:00:00, it will be rounded down to 00:00:00 on the date. For example, if StartTime is 2018-09-04 10:40:00, it will be rounded down to 2018-09-04 00:00:00.
Only data from the last 90 days will be queried.
EndTime Yes Timestamp Query end time in the format of yyyy-MM-dd HH:mm:ss
Only supports data query at daily granularity. The date in the input parameter is used as the end date.
If the specified end date is smaller than 23:59:59, it will be rounded up to 23:59:59 on the date. For example, if EndTime is 2018-09-05 22:40:00, it will be rounded up to 2018-09-05 23:59:59.
EndTime must be later than or equal to StartTime
Metric Yes String Objects to be sorted. Valid values:
url: Sort by access URL (URLs carrying no parameters). Supported filters are flux and request.
district: sorts provinces or countries/regions. Supported filters are flux and request.
isp: sorts ISPs. Supported filters are flux and request.
host: Sort by domain name access data. Supported filters are flux, request, bandwidth, fluxHitRate, and statusCode (2XX, 3XX, 4XX, 5XX).
originHost: Sort by domain name origin-pull data. Supported filters are flux, request, bandwidth, and OriginStatusCode (origin_2XX, origin_3XX, origin_4XX, origin_5XX).
Filter Yes String Metric name used for sorting:
flux: If Metric is host, it indicates the access traffic; if Metric is originHost, it indicates the origin-pull traffic.
bandwidth: If Metric is host, it indicates the access bandwidth; if Metric is originHost, it indicates the origin-pull bandwidth.
request: If Metric is host, it indicates the number of access requests; if Metric is originHost, it indicates the number of origin-pull requests.
fluxHitRate: Average traffic hit rate
2XX: access 2XX status code
3XX: access 3XX status code
4XX: access 4XX status code
5XX: access 5XX status code
origin_2XX: origin-pull 2XX status code
origin_3XX: origin-pull 3XX status code
origin_4XX: origin-pull 4XX status code
origin_5XX: origin-pull 5XX status code
statusCode: statistics of a specific access status code which is specified in the Code parameter.
OriginStatusCode: statistics of a specific origin-pull status code which is specified in the Code parameter.
Domains.N No Array of String Specifies the list of domain names to be queried; up to 30 domain names can be queried at a time.
Project No Integer Specifies the project ID to be queried, which can be viewed here
Please note that if domain names are specified, this parameter will be ignored.
Detail No Boolean The sorted results of all domain names are returned by default (false) during a multi-domain-name query
If Metric is url, path, district, or isp and Filter is flux or request, it can be set to true to return the sorted results of each domain.
Code No String When Filter is statusCode or OriginStatusCode, enter a code to query and sort results.
Area No String Specifies the service region. If this value is left blank, it means to query CDN data within the Chinese mainland.
mainland: Query CDN data in the Chinese mainland.
overseas: Query CDN data outside the Chinese mainland. Supported metrics are url, district, host, and originHost. If Metric is originHost, supported filters are flux, request, and bandwidth.
AreaType No String Specifies a region type for the query. If it is left blank, data of the service region will be queried. This parameter is only valid when Area is overseas and Metric is district or host.
server: Query by the location of server (Tencent Cloud CDN nodes).
client: Query data of the client region where the request devices are located; if Metric is host, supported filters are flux, request, and bandwidth.
Product No String Specifies the product to query, either cdn (default) or ecdn.
Limit No Integer Returns the first N data entries. The default value is 100 if this parameter is not specified, whereas 1000 if Metric is url.

3. Output Parameters

Parameter Name Type Description
Data Array of TopData Top access data details of each resource
RequestId String The unique request ID, which is returned for each request. RequestId is required for locating a problem.

4. Example

Example1 Querying top URL access data

Input Example

https://cdn.tencentcloudapi.com/?Action=ListTopData
&StartTime=2018-09-04 00:00:00
&EndTime=2018-09-04 12:00:00
&Metric=Url
&Filter=flux
&Domains.0=www.test.com
&Domains.1=www.test.com
&<Common request parameters>

Output Example

{
    "Response": {
        "RequestId": "123",
        "Data": [
            {
                "Resource": "www.test1.com",
                "DetailData": [
                    {
                        "Name": "www.test1.com/1.jpg?abc=123",
                        "Value": 13838
                    }
                ]
            },
            {
                "Resource": "www.test2.com",
                "DetailData": [
                    {
                        "Name": "http://www.test2.com/1.jpg?abc=123",
                        "Value": 2501
                    }
                ]
            }
        ]
    }
}

5. Developer Resources

SDK

TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

Command Line Interface

6. Error Code

The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

Error Code Description
FailedOperation.CdnConfigError Failed to update the domain name configuration. Please submit a ticket for troubleshooting.
InternalError.CamSystemError Authentication system internal error.
InternalError.CdnConfigError Failed to update the domain name configuration.
InternalError.CdnDbError Internal data error. Please submit a ticket for troubleshooting.
InternalError.CdnQuerySystemError Internal error. Please try again or contact the customer service for assistance.
InternalError.CdnSystemError System error. Please submit a ticket for troubleshooting.
InternalError.DataSystemError Error with the data query. Please submit a ticket for troubleshooting.
InternalError.Error Service internal error. Please submit a ticket for troubleshooting.
InternalError.ProxyServer Internal service error. Please submit a ticket for troubleshooting.
InternalError.RouteError Internal service error. Please submit a ticket for troubleshooting.
InternalError.TagSystemError Tag internal error. Please submit a ticket for troubleshooting.
InvalidParameter.CdnHostInvalidParam Invalid domain name format. Please check and try again.
InvalidParameter.CdnInterfaceError Internal API error. Please submit a ticket for troubleshooting.
InvalidParameter.CdnParamError Parameter error. Please see the sample parameters in the documentation.
InvalidParameter.CdnStatInvalidDate Invalid date. Please see the sample date in the documentation.
InvalidParameter.CdnStatInvalidFilter Invalid statistical dimension. Please see the sample statistical analysis in the documentation.
InvalidParameter.CdnStatInvalidMetric Invalid statistical type. Please see the sample statistical analysis in the documentation.
InvalidParameter.CdnStatInvalidProjectId Incorrect project ID. Please check and try again.
InvalidParameter.CdnStatTooManyDomains The number of queried domain names reached the limit.
LimitExceeded.CdnHostOpTooOften Domain name operations are too frequent.
ResourceNotFound.CdnHostNotExists Unable to find the domain name. Please make sure the domain name is correct.
ResourceNotFound.CdnProjectNotExists The project does not exist. Please check and try again.
ResourceNotFound.CdnUserNotExists The CDN service has not been activated. Please activate it first before using this API.
UnauthorizedOperation.CdnAccountUnauthorized The sub-account is unauthorized to query full data.
UnauthorizedOperation.CdnCamUnauthorized No CAM policy is configured for the sub-account.
UnauthorizedOperation.CdnHostUnauthorized The sub-account has no access to the CDN-accelerated domain name.
UnauthorizedOperation.CdnProjectUnauthorized The project is not authorized for the sub-account.
UnauthorizedOperation.CdnUserIsSuspended The CDN service has been suspended. Please restart it and try again.
UnauthorizedOperation.CdnUserNoWhitelist You are not in the beta whitelist and thus have no permission to use this function.
UnauthorizedOperation.OperationTooOften Too many calling attempts.
Contact Us

Contact our sales team or business advisors to help your business.

Technical Support

Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

7x24 Phone Support