tencent cloud

APIs

DocumentationAPIsLLM Service TokenHubUsage Statistics APIsDescribeUsageRankList

DescribeUsageRankList

Download
Focus Mode
Font Size
Last updated: 2026-08-26 20:54:58

1. API Description

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.
    Metrics returned: TotalToken (total) / InputTotalToken (input) / OutputTotalToken (output) / CacheTotalToken (read cache).
  • search: [To be launched] Online search usage statistics. Supports Dimension = apikey / endpoint / model.
    Returns metrics: SearchRequestCount (search request count)/SearchCount (search engine call count).

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.

  • TopList: A list of objects sorted by MetricKeys[0] in descending order, including the aggregated value over the entire period and point-in-time curves.

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: 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.

  • tokens (default): Token consumption chart (statistics=sum), supports Dimension = apikey/endpoint/model
  • search [to be launched]: Online search call count (statistics=sum), only supports Dimension = model
  • Other values return InvalidParameter.

Enum values:

  • tokens: tokens
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.

  • false (default): Return TopList in pages by Offset (10 items per page). Each object contains
    Series time series points for drawing curves.
  • true: Ignore Offset and return the full object list without Series (CSV export scenario).

3. Output Parameters

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 MetricKeys[0] in descending order. When ShowAll=false, it is the 10 objects on the current page (including Series); when ShowAll=true, it is all objects (excluding Series, used for CSV export).
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.

4. Example

Example1 DescribeUsageRankList

Input Example

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-**************************"
}

Output Example

{
    "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"
    }
}

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
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
Previous Topic: DescribeTokenPlanApiKeyUsageDetailNext Topic: Data Types

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback