DescribeBillingData
1. API Description
Domain name for API request: teo.intl.tencentcloudapi.com.
This API is used to query billing data.
A maximum of 50 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: DescribeBillingData. |
| Version | Yes | String | Common Params. The value used for this API: 2022-09-01. |
| Region | No | String | Common Params. This parameter is not required. |
| StartTime | Yes | Timestamp ISO8601 | The start time. |
| EndTime | Yes | Timestamp ISO8601 | The end time. The query time range (EndTime - StartTime) must be less than or equal to 31 days. |
| ZoneIds.N | Yes | Array of String | Zone ID set. This parameter is required. A maximum of 100 zone IDs can be passed in. If you need to query data for all zones under the Tencent Cloud main account, please use "*" instead. To query account-level data, you need to have full resource permissions for all zones of this interface. |
| MetricName | Yes | String | Metric name. Valid values: Layer 4/7 Acceleration Traffic (Unit: Byte): Layer 4/7 Acceleration Bandwidth (Unit: bps): HTTP/HTTPS Security Requests (Unit: counts): Value-added Service Usage: Edge Computing Usage: Media Processing Usage (Unit: seconds): |
| Interval | Yes | String | Time granularity of the query. Valid values: |
| Filters.N | No | Array of BillingDataFilter | Filter criteria. The detailed values of filter criteria are as follows:
Note: Filters of the same |
| GroupBy.N | No | Array of String | Grouping aggregation dimensions. A maximum of two dimensions can be used for grouping simultaneously. The values are as follows:
|
3. Output Parameters
| Parameter Name | Type | Description |
|---|---|---|
| Data | Array of BillingData | Data point list. Note: This field may return null, which indicates a failure to obtain a valid value. |
| RequestId | String | The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem. |
4. Example
Example1 Querying content acceleration traffic in the specified zone and billing region
This example shows you how to query the billing volume of content acceleration traffic with a specific zone ID and region ID on a daily granularity.
Input Example
POST / HTTP/1.1
Host: teo.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeBillingData
<Common Request Parameters>
{
"StartTime": "2024-01-01T00:00:00+08:00",
"EndTime": "2024-01-24T03:20:00+08:00",
"Interval": "day",
"MetricName": "acc_flux",
"Filters": [
{
"Type": "region-id",
"Value": "MidEast"
}
],
"ZoneIds": [
"zone-2smdfso9dr58"
]
}
Output Example
{
"Response": {
"RequestId": "457e8933-4296-4878-9a7f-fb888559e29e",
"Data": [
{
"Time": "2023-12-31T16:00:00Z",
"Value": 0
},
{
"Time": "2024-01-01T16:00:00Z",
"Value": 0
},
{
"Time": "2024-01-02T16:00:00Z",
"Value": 0
},
{
"Time": "2024-01-03T16:00:00Z",
"Value": 0
},
{
"Time": "2024-01-04T16:00:00Z",
"Value": 0
},
{
"Time": "2024-01-05T16:00:00Z",
"Value": 0
},
{
"Time": "2024-01-06T16:00:00Z",
"Value": 0
},
{
"Time": "2024-01-07T16:00:00Z",
"Value": 0
},
{
"Time": "2024-01-08T16:00:00Z",
"Value": 0
},
{
"Time": "2024-01-09T16:00:00Z",
"Value": 0
},
{
"Time": "2024-01-10T16:00:00Z",
"Value": 0
},
{
"Time": "2024-01-11T16:00:00Z",
"Value": 0
},
{
"Time": "2024-01-12T16:00:00Z",
"Value": 0
},
{
"Time": "2024-01-13T16:00:00Z",
"Value": 0
},
{
"Time": "2024-01-14T16:00:00Z",
"Value": 0
},
{
"Time": "2024-01-15T16:00:00Z",
"Value": 0
},
{
"Time": "2024-01-16T16:00:00Z",
"Value": 0
},
{
"Time": "2024-01-17T16:00:00Z",
"Value": 0
},
{
"Time": "2024-01-18T16:00:00Z",
"Value": 0
},
{
"Time": "2024-01-19T16:00:00Z",
"Value": 0
},
{
"Time": "2024-01-20T16:00:00Z",
"Value": 0
},
{
"Time": "2024-01-21T16:00:00Z",
"Value": 0
},
{
"Time": "2024-01-22T16:00:00Z",
"Value": 0
},
{
"Time": "2024-01-23T16:00:00Z",
"Value": 0
}
]
}
}
Example2 Query content acceleration traffic for specified zones and group by zone ID
Query the billing usage of content acceleration traffic for specified zone-ids, grouped by zone-id with a daily time granularity.
Input Example
POST / HTTP/1.1
Host: teo.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeBillingData
<Common Request Parameters>
{
"StartTime": "2025-07-01T00:00:00+08:00",
"EndTime": "2025-07-02T23:59:59+08:00",
"Interval": "day",
"MetricName": "acc_flux",
"ZoneIds": [
"zone-2m2gq4dnpmd2",
"zone-30hqppzribht"
],
"GroupBy": [
"zone-id"
]
}
Output Example
{
"Response": {
"RequestId": "d2174285-8aac-4cdc-bc06-d81f2f6520da",
"Data": [
{
"Time": "2025-06-30T16:00:00Z",
"Value": 0,
"ZoneId": "zone-2m2gq4dnpmd2"
},
{
"Time": "2025-07-01T16:00:00Z",
"Value": 2751240612,
"ZoneId": "zone-2m2gq4dnpmd2"
},
{
"Time": "2025-06-30T16:00:00Z",
"Value": 0,
"ZoneId": "zone-30hqppzribht"
},
{
"Time": "2025-07-01T16:00:00Z",
"Value": 68443435,
"ZoneId": "zone-30hqppzribht"
}
]
}
}
Example3 Query content acceleration traffic for specified zones and group by domain
Query the billing usage of content acceleration traffic for specified zone-ids, grouped by domain name with a daily time granularity.
Input Example
POST / HTTP/1.1
Host: teo.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeBillingData
<Common Request Parameters>
{
"StartTime": "2025-07-01T00:00:00+08:00",
"EndTime": "2025-07-02T23:59:59+08:00",
"Interval": "day",
"MetricName": "acc_flux",
"ZoneIds": [
"zone-2m2gq4dnpmd2",
"zone-30hqppzribht"
],
"GroupBy": [
"host"
]
}
Output Example
{
"Response": {
"RequestId": "d2174285-8aac-4cdc-bc06-d81f2f6520da",
"Data": [
{
"Host": "test1.example.com",
"Time": "2025-06-30T16:00:00Z",
"Value": 1387001003,
"ZoneId": "zone-2m2gq4dnpmd2"
},
{
"Host": "test1.example.com",
"Time": "2025-07-01T16:00:00Z",
"Value": 1390529805,
"ZoneId": "zone-2m2gq4dnpmd2"
},
{
"Host": "test2.example.com",
"Time": "2025-06-30T16:00:00Z",
"Value": 2879078,
"ZoneId": "zone-2m2gq4dnpmd2"
},
{
"Host": "test2.example.com",
"Time": "2025-07-01T16:00:00Z",
"Value": 2889084,
"ZoneId": "zone-2m2gq4dnpmd2"
}
]
}
}
Example4 Query content acceleration traffic for specified zones grouped by zone ID and billing region
Query the billing usage of content acceleration traffic for specified zone IDs, grouped by both zone ID and billing region with daily time granularity.
Input Example
POST / HTTP/1.1
Host: teo.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeBillingData
<Common Request Parameters>
{
"StartTime": "2025-07-01T00:00:00+08:00",
"EndTime": "2025-07-02T23:59:59+08:00",
"Interval": "day",
"MetricName": "acc_flux",
"ZoneIds": [
"zone-2m2gq4dnpmd2",
"zone-30hqppzribht"
],
"GroupBy": [
"zone-id",
"region-id"
]
}
Output Example
{
"Response": {
"RequestId": "d2174285-8aac-4cdc-bc06-d81f2f6520da",
"Data": [
{
"RegionId": "SA",
"Time": "2025-06-30T16:00:00Z",
"Value": 549591531,
"ZoneId": "zone-2m2gq4dnpmd2"
},
{
"RegionId": "SA",
"Time": "2025-07-01T16:00:00Z",
"Value": 549591531,
"ZoneId": "zone-2m2gq4dnpmd2"
},
{
"RegionId": "MidEast",
"Time": "2025-06-30T16:00:00Z",
"Value": 549591531,
"ZoneId": "zone-30hqppzribht"
},
{
"RegionId": "MidEast",
"Time": "2025-07-01T16:00:00Z",
"Value": 549591531,
"ZoneId": "zone-30hqppzribht"
}
]
}
}
5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.
- Tencent Cloud SDK 3.0 for Python
- Tencent Cloud SDK 3.0 for Java
- Tencent Cloud SDK 3.0 for PHP
- Tencent Cloud SDK 3.0 for Go
- Tencent Cloud SDK 3.0 for Node.js
- Tencent Cloud SDK 3.0 for .NET
- Tencent Cloud SDK 3.0 for C++
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 |
|---|---|
| InternalError.ProxyServer | An unknown error occurred in the backend server. |
| InvalidParameter.GroupByLimitExceeded | |
| InvalidParameter.InvalidInterval | Invalid interval. The value should be either [min 5min hour day]. |
| InvalidParameter.InvalidMetric | The query dimension is invalid. |
| InvalidParameter.ZoneHasNotBeenBoundToPlan | The zone is not bound to a package. |