Usage

Query Usage Details

Query token usage records within a specified time range using a Management API Key.

Authentication

Management API Key authentication is required.

Authorization: Bearer <management_api_key>

Request

GET /management/usage

Query Parameters

Parameter	Type	Required	Description
start_time	int64	Yes	Start time as Unix timestamp
end_time	int64	Yes	End time as Unix timestamp
model	string	No	Filter by model
token_id	string	No	Filter by token ID
user_id	string	No	Organization admins can filter by member
page	uint64	No	Default is 1
pagesize	uint64	No	Default is 20

Time Range Constraints

• start_time and end_time must both be greater than 0
• start_time must be less than end_time
• A single query cannot exceed a 31-day time range

Request Examples

cURL

curl -X GET "https://portal-api.r9s.ai/api/v1/portal/management/usage?start_time=1735689600&end_time=1736294400&page=1&pagesize=20" \
  -H "Authorization: Bearer sk_mg_xxxxxxxxxxxxxxxxxx"

JavaScript (Fetch)

const response = await fetch('https://portal-api.r9s.ai/api/v1/portal/management/usage?start_time=1735689600&end_time=1736294400&page=1&pagesize=20', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer sk_mg_xxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);

Python (requests)

import requests

url = "https://portal-api.r9s.ai/api/v1/portal/management/usage"
params = {
    "start_time": 1735689600,
    "end_time": 1736294400,
    "page": 1,
    "pagesize": 20
}
headers = {
    "Authorization": "Bearer sk_mg_xxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json"
}

response = requests.get(url, params=params, headers=headers)
data = response.json()
print(data)

Response Schema

Field	Type	Required	Description
meta	object	Yes	Response metadata
meta.code	integer	Yes	Status code (0 for success)
meta.message	string	Yes	Response message
meta.request_id	string	Yes	Request identifier
data	object	Yes	Usage data
data.list	array	Yes	Usage records list
data.list[].id	string	Yes	Record ID
data.list[].request_time	int64	Yes	Request timestamp
data.list[].user_id	string	Yes	User ID
data.list[].custom_user_id	string	Yes	Custom user ID
data.list[].token_id	string	Yes	Token ID
data.list[].model	string	Yes	Model name
data.list[].model_type	integer	Yes	Model type
data.list[].input_token	integer	Yes	Input token count
data.list[].output_token	integer	Yes	Output token count
data.list[].input_price	number	Yes	Input price
data.list[].output_price	number	Yes	Output price
data.list[].cached_token	integer	Yes	Cached token count
data.list[].cached_price	number	Yes	Cached price
data.list[].total_amount	number	Yes	Total amount
data.list[].discount_amount	number	Yes	Discount amount
data.list[].amount	number	Yes	Final amount
data.list[].channel_id	integer	Yes	Channel ID
data.list[].user_name	string	Yes	User name
data.total	integer	Yes	Total number of records

Response Example

{
  "meta": {
    "code": 0,
    "message": "success",
    "request_id": "xxx"
  },
  "data": {
    "list": [
      {
        "id": "1912345678901234567",
        "request_time": 1710000000,
        "user_id": "10001",
        "custom_user_id": "ext-user-01",
        "token_id": "tk_xxx",
        "model": "gpt-4.1",
        "model_type": 1,
        "input_token": 1024,
        "output_token": 256,
        "input_price": 0.01,
        "output_price": 0.02,
        "cached_token": 0,
        "cached_price": 0,
        "total_amount": 0.03,
        "discount_amount": 0,
        "amount": 0.03,
        "channel_id": 12,
        "user_name": "alice"
      }
    ],
    "total": 1
  }
}

Organization Admin Notes

• If the API Key belongs to an organization admin context, user_id can be provided to query a specific member.
• In that case, the server ignores the token_id filter.

Common Errors

Scenario	Typical Error
Missing authentication info	unauthorized
Time range exceeds 31 days	time range must not exceed 31 days

Related APIs

• Overview - Learn about Manager API authentication and basic information
• API Keys - Manage API Keys
• Balance - Retrieve current account balance information