查询生成用量日志

查询当前 API Key 关联的生成用量记录。

GET/api/v1/generations/logs

字段	值
Base URL	https://api.gate.ai
认证	Authorization: Bearer <API_KEY>
格式	Gate.AI REST JSON
限流	每个 API Key 每秒 1 次请求

支持按 trace_id 查询该 Trace 下的全部记录，或查询当前 API Key 最近 100 条记录。

按 Trace 查询：请求体包含合法 trace_id ，返回全部属于当前 API Key 且 Trace 精确匹配的记录，按 id DESC 排序。
查询最近记录：不发送请求体、发送空请求体或发送 {} ，返回当前 API Key 最近 100 条记录，按 created_at DESC, id DESC 排序。
Trace 不存在、日志尚未生成或不属于当前 API Key 时，返回 HTTP 200 和空数组。

请求参数

名称	位置	类型	必选	说明
Authorization	header	string	是	API Key 鉴权，格式：Bearer <API_KEY>
Content-Type	header	string	是	固定为 application/json

请求体

名称	类型	必选	说明
trace_id	string	否	精确查询指定 Trace，区分大小写，长度为 1～128 字符。

示例：按 Trace 查询

bash

1curl -X POST 'https://api.gate.ai/api/v1/generations/logs' \2  -H 'Authorization: Bearer <API_KEY>' \3  -H 'Content-Type: application/json' \4  -d '{"trace_id":"Trace-AbC-123"}'

示例：查询最近 100 条

bash

1curl -X POST 'https://api.gate.ai/api/v1/generations/logs' \2  -H 'Authorization: Bearer <API_KEY>' \3  -H 'Content-Type: application/json' \4  -d '{}'

返回字段说明

名称	类型	说明
code	integer	业务状态码，成功固定为 200。
msg	string	状态描述，成功固定为 success。
timestamp	string	服务端当前 Unix 秒时间戳。
data	array	用量日志数组；无匹配记录时为[]。
data[].id	integer	用量记录 ID。
data[].trace_id	string	请求 Trace ID。
data[].span_id	string	请求 Span ID。
data[].session_id	string	会话 ID。
data[].api_key_id	string	产生该记录的 API Key ID。
data[].user_id	string	用户 ID。
data[].app	string	调用应用标识。
data[].standard_model	string	标准模型名称。
data[].usage_model	string	实际用于计量的模型名称。
data[].stream	boolean	原请求是否使用流式响应。
data[].response_status	integer	原请求 HTTP 响应状态码。
data[].latency	integer	原请求耗时，单位为毫秒。
data[].input_tokens	integer	输入 Token 数。
data[].output_tokens	integer	输出 Token 数。
data[].total_tokens	integer	Token 总数。
data[].cache_read_tokens	integer	缓存读取 Token 数。
data[].cache_write_tokens	integer	缓存写入 Token 数。
data[].input_tokens_details	string	输入 Token 明细，保留存储时的字符串格式。
data[].output_tokens_details	string	输出 Token 明细，保留存储时的字符串格式。
data[].input_cost	string	输入费用，十进制字符串。
data[].output_cost	string	输出费用，十进制字符串。
data[].cache_read_cost	string	缓存读取费用，十进制字符串。
data[].cache_write_cost	string	缓存写入费用，十进制字符串。
data[].total_cost	string	总费用，十进制字符串。
data[].is_free	boolean	本次调用是否由免费额度覆盖。
data[].timestamp	string	用量发生时间，ISO 8601 UTC。
data[].created_at	string	记录创建时间，ISO 8601 UTC。
data[].metadata	string	调用扩展信息，保留存储时的字符串格式。

返回示例

json

1{2  "code": 200,3  "msg": "success",4  "timestamp": "1784633852",5  "data": [6    {7      "id": 42,8      "trace_id": "Trace-AbC-123",9      "span_id": "span-001",10      "session_id": "session-001",11      "api_key_id": "1001",12      "user_id": "2002",13      "app": "example-client",14      "standard_model": "openai/gpt-5",15      "usage_model": "gpt-5",16      "stream": false,17      "response_status": 200,18      "latency": 842,19      "input_tokens": 120,20      "output_tokens": 80,21      "total_tokens": 200,22      "cache_read_tokens": 20,23      "cache_write_tokens": 0,24      "input_tokens_details": "{"cached_tokens":20}",25      "output_tokens_details": "{"reasoning_tokens":10}",26      "input_cost": "0.00120000",27      "output_cost": "0.00160000",28      "cache_read_cost": "0.00002000",29      "cache_write_cost": "0.00000000",30      "total_cost": "0.00282000",31      "is_free": false,32      "timestamp": "2026-07-21T08:30:00Z",33      "created_at": "2026-07-21T08:30:01Z",34      "metadata": "{"request_type":"audio"}"35    }36  ]37}

无匹配记录

json

1{2  "code": 200,3  "msg": "success",4  "timestamp": "1784633852",5  "data": []6}

返回结果

状态码	状态码含义	说明	数据模型
200	OK	查询成功；无匹配记录时 data 为空数组。	UsageLogResponse
400	Bad Request	JSON 请求体非法，或 trace_id 类型、长度不合法。	ErrorResponse
401	Unauthorized	API Key 缺失、无效、过期、撤销、禁用或未激活。	ErrorResponse
403	Forbidden	预留给未来 API Key 权限策略。	ErrorResponse
429	Too Many Requests	同一 API Key 超过每秒 1 次请求；响应包含 Retry-After。	ErrorResponse
500	Internal Server Error	数据库查询失败或网关内部错误。	ErrorResponse

错误返回示例

json

1{2  "error": {3    "type": "invalid_request_error",4    "message": "invalid API key"5  }6}