Lấy mức sử dụng theo Key

GET /api/open/v1/usage/keys

Tham số yêu cầu

Tham số	Vị trí	Kiểu	Bắt buộc	Mặc định	Mô tả
start_timestamp	query	integer	Không	Xem bên dưới	Thời gian bắt đầu (bao gồm), giây unix
end_timestamp	query	integer	Không	Xem bên dưới	Thời gian kết thúc (bao gồm), giây unix
group_by	query	string	Không	key_name	Cách nhóm: key_name nhóm theo tên Key tại thời điểm yêu cầu, các Key trùng tên được gộp thành một dòng; key_id mỗi Key một dòng
key_id	query	integer	Không	—	Lọc theo ID Key, số nguyên dương; lặp lại tham số hoặc dùng dấu phẩy cho nhiều giá trị. Truyền ID của người dùng khác chỉ trả về kết quả rỗng
key_name	query	string	Không	—	Tên Key chính xác tại thời điểm yêu cầu; lặp lại tham số cho nhiều giá trị. Không hỗ trợ dấu phẩy vì tên có thể chứa dấu phẩy
p	query	integer	Không	1	Số trang, từ 1 đến 1000000
page_size	query	integer	Không	10	Số mục mỗi trang, từ 1 đến 1000
sort_by	query	string	Không	total_tokens	Trường sắp xếp: key_count (chỉ với group_by=key_name), prompt_tokens, completion_tokens, total_tokens hoặc amount
order	query	string	Không	desc	Chiều sắp xếp: asc hoặc desc

Quy tắc khoảng thời gian:

• Bỏ trống cả hai: 30 ngày gần nhất.
• Chỉ có start_timestamp: 30 ngày tính về sau, tối đa đến thời điểm hiện tại.
• Chỉ có end_timestamp: 30 ngày tính về trước.
• Khoảng thời gian tối đa 366 ngày.

Mỗi tham số đa giá trị nhận tối đa 50 giá trị; vượt quá sẽ trả về 400 invalid_request. p / page_size được truyền rõ ràng nhưng không hợp lệ sẽ trả về 400; xem Phân trang.

Ví dụ yêu cầu

curl "https://www.routeapi.ai/api/open/v1/usage/keys?start_timestamp=1726400000&end_timestamp=1729000000&sort_by=total_tokens&order=desc&p=1&page_size=20" \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY"

Ví dụ phản hồi

{
  "success": true,
  "message": "",
  "data": {
    "items": [
      {
        "key_name": "bot",
        "key_count": 2,
        "prompt_tokens": 5000,
        "completion_tokens": 1000,
        "total_tokens": 6000,
        "amount": 0.20
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20,
    "start_timestamp": 1726400000,
    "end_timestamp": 1729000000
  }
}

Khi group_by=key_id, mỗi Key một dòng, có key_id và không có key_count:

{
  "success": true,
  "message": "",
  "data": {
    "items": [
      {
        "key_id": 12,
        "key_name": "bot",
        "prompt_tokens": 3000,
        "completion_tokens": 600,
        "total_tokens": 3600,
        "amount": 0.12
      },
      {
        "key_id": 15,
        "key_name": "bot",
        "prompt_tokens": 2000,
        "completion_tokens": 400,
        "total_tokens": 2400,
        "amount": 0.08
      }
    ],
    "total": 2,
    "page": 1,
    "page_size": 20,
    "start_timestamp": 1726400000,
    "end_timestamp": 1729000000
  }
}

Trường phản hồi

Trường	Kiểu	Mô tả
items[].key_id	integer	Chỉ với group_by=key_id. ID của Key, dùng được cho các API như Lấy một API Key; 0 biểu thị mức sử dụng không qua API Key (như Playground)
items[].key_name	string	group_by=key_name: tên của Key tại thời điểm yêu cầu. group_by=key_id: tên hiện tại của Key; nếu Key không còn tồn tại hoặc key_id là 0, lấy tên tại yêu cầu gần nhất của Key đó trong khoảng thời gian
items[].key_count	integer	Chỉ với group_by=key_name. Số Key khác nhau có tên này và có tiêu thụ trong khoảng thời gian
items[].prompt_tokens	integer	Tổng token đầu vào của dòng này
items[].completion_tokens	integer	Tổng token đầu ra của dòng này
items[].total_tokens	integer	Tổng token đầu vào và đầu ra
items[].amount	number	Số tiền đã tiêu thụ của dòng này (đã trừ hoàn tiền), theo tiền tệ của trang, hai chữ số thập phân
total	integer	Tổng số dòng: với group_by=key_name là số tên, với group_by=key_id là số Key (bao gồm dòng có key_id là 0)
page	integer	Số trang hiện tại
page_size	integer	Số mục thực tế mỗi trang
start_timestamp	integer	Thời gian bắt đầu thực tế
end_timestamp	integer	Thời gian kết thúc thực tế

Lỗi

HTTP	code	Tình huống
400	invalid_request	group_by, sort_by hoặc order không hợp lệ, sort_by=key_count khi group_by=key_id, key_id không phải số nguyên dương, timestamp không phải số hoặc âm, khoảng thời gian không hợp lệ, tham số phân trang không hợp lệ, hoặc tham số đa giá trị vượt quá 50 giá trị
429	—	Vượt giới hạn truy vấn theo người dùng (mặc định 30/phút); body có thể trống

Các mã lỗi chung khác xem tại Lỗi API nền tảng.

Lưu ý

• Tên Key có thể trùng nhau: group_by=key_name gộp các Key cùng tên thành một dòng; khi cần phân biệt, dùng group_by=key_id. Không trả về giá trị Key.
• Trước tiên sắp xếp theo trường sort_by, khi bằng nhau thì theo key_name (với group_by=key_id là theo key_id) tăng dần nên phân trang ổn định.
• Bản ghi lịch sử lưu tên Key tại thời điểm yêu cầu, đổi tên không ghi lại quá khứ. Vì vậy với group_by=key_name, mức sử dụng trước và sau khi đổi tên tách thành hai dòng; bộ lọc key_name cũng khớp với tên tại thời điểm yêu cầu, còn group_by=key_id trả về tên hiện tại nên hai giá trị có thể khác nhau.
• Tổng amount của các dòng bằng số tiền trong Thống kê mức sử dụng (không tính sai số làm tròn).
• Chỉ tính log tiêu thụ (tính phí), không bao gồm yêu cầu thất bại.
• Số token là số đếm thô, không phải đơn vị triệu.
• Số tiền dùng tiền tệ hiển thị của trang, xem Lấy số dư.
• amount của mỗi dòng được làm tròn riêng, nên tổng các dòng có thể lệch tới 0,01.
• Để xuất Excel, hãy phân trang endpoint này với cùng bộ lọc và tổng hợp các mảng items.
• Endpoint này dùng chung giới hạn truy vấn theo người dùng (mặc định 30/phút) với Mức sử dụng, Log của tài khoản, Xuất log và Mức sử dụng theo mô hình. Xem Giới hạn tần suất.