Domain name for API request: tokenhub.intl.tencentcloudapi.com.
Query the usage ranking list.
Metric family (MetricType)
tokens (default): Token usage statistics. Supports Dimension = apikey / endpoint / model.search: [To be launched] Online search usage statistics. Supports Dimension = apikey / endpoint / model.content
-The MetricType field is used to switch metric families. The response echoes back MetricType and MetricKeys.
-TotalStats: The aggregated value of all objects over the entire time window.
-PageStats: The aggregated value of objects on the current page.
A maximum of 20 requests can be initiated per second for this API.
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: DescribeUsageRankList. |
| Version | Yes | String | Common Params. The value used for this API: 2026-03-22. |
| Region | Yes | String | Common Params. For more information, please see the list of regions supported by the product. |
| Dimension | Yes | String | Statistical dimension. Values: apikey (statistics by APIKey), endpoint (statistics by access point), model (statistics by model). |
| StartTime | Yes | Timestamp ISO8601 | Start time (inclusive interval), in RFC3339 format. |
| EndTime | Yes | Timestamp ISO8601 | End time (open interval) in RFC3339 format. The maximum span from StartTime is 90 days. |
| MetricType | No | String | Metric family switch field.
Enum values:
|
| Target | No | String | Dimension filtering value. An empty string indicates querying all objects; a non-empty string indicates querying only the specified single object (for example, a designated APIKey ID). Maximum 256 characters. |
| Period | No | Integer | Statistical granularity (seconds). Value: 60, 300, 3600, 86400. Must not be less than the lower limit corresponding to the span: span ≤ 1 day → 60; 1–5 days → 300; 5–10 days → 3600; > 10 days → 86400. Used only when ShowAll=false. |
| Offset | No | Integer | Pagination starting point, starting from 0, default 0. Ignore timing when ShowAll=true. Page size fixed as 10. |
| ShowAll | No | Boolean | Whether to return full result.
|
| Parameter Name | Type | Description |
|---|---|---|
| Dimension | String | Statistical dimension of the backfill request. |
| MetricType | String | Metrics family of the backfill request: tokens / search. |
| MetricKeys | Array of String | List of metric keys actually included in Stats / Series / PageStats / TotalStats in this response, case-sensitive by MetricType: tokens=[Total,Input,Output,Cache], search=[SearchRequestCount,SearchCount] |
| ViewName | String | View (data source) |
| Period | Integer | Statistical granularity (in seconds) of the backfill request. It is 0 when ShowAll=true. |
| StartTime | Timestamp ISO8601 | Backfill the start time of the request. |
| EndTime | Timestamp ISO8601 | End time of the backfill request. |
| Total | Integer | Total number of objects. |
| Offset | Integer | Backfill the pagination starting point of the request. It is 0 when ShowAll=true. |
| Limit | Integer | Page size. It is always 10. When ShowAll=true, it is Total. |
| Timestamps | Array of Integer | Timestamp sequence corresponding to the Series array (Unix seconds). Empty array when ShowAll=true. |
| TopList | Array of UsageRankItem | Object ranking list, sorted by |
| PageStats | UsageStats | Pagination statistics result |
| TotalStats | UsageStats | Total statistics result |
| 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. |
POST / HTTP/1.1
Host: tokenhub.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeUsageRankList
<Common request parameters>
{
"Dimension": "apikey",
"StartTime": "2026-04-09T00:00:00+08:00",
"EndTime": "2026-05-09T00:00:00+08:00",
"Period": 86400,
"Target": "ak-20260618-**************************"
}{
"Response": {
"Dimension": "apikey",
"EndTime": "2026-05-09T00:00:00+08:00",
"Limit": 0,
"MetricKeys": [
"TotalToken",
"InputTotalToken",
"OutputTotalToken"
],
"MetricType": "tokens",
"Offset": 0,
"PageStats": {
"InputTotalToken": 0,
"OutputTotalToken": 0,
"TotalToken": 0
},
"Period": 86400,
"RequestId": "1568bc1c-946b-4c2b-b69f-6ba93f2bb258",
"StartTime": "2026-04-09T00:00:00+08:00",
"Timestamps": [],
"TopList": [],
"Total": 0,
"TotalStats": {
"InputTotalToken": 0,
"OutputTotalToken": 0,
"TotalToken": 0
},
"ViewName": "tokenhub_uin_apikeyid"
}
}TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.
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.BaradError | InternalError.BaradError |
| InternalError.InternalError | InternalError.InternalError |
| InvalidParameter.InvalidParameter | InvalidParameter.InvalidParameter |
| InvalidParameter.PeriodExceedsSpan | InvalidParameter.PeriodExceedsSpan |
| InvalidParameter.PeriodTooFineForData | InvalidParameter.PeriodTooFineForData |
| InvalidParameter.TooManyObjects | InvalidParameter.TooManyObjects |
| MissingParameter.MissingParameter | MissingParameter.MissingParameter |
| UnauthorizedOperation.UnauthorizedOperation | UnauthorizedOperation.UnauthorizedOperation |
文档反馈