请求日志
Markdown 版账户最近的 API 请求和检索调用的轨迹。
列出请求日志
GET/v2/request-logs
账户最近的 API 请求,按时间倒序:方法、路由、状态码、错误码、耗时、Key、主体、请求 id、轨迹 id 和客户端。只记录元数据。保留 retention_days 天(默认 14 天,部署可设为 1 到 90 天)。请求约在一秒内出现在列表中。状态码为 429 的响应,每个 Key(或主体)、每条路由每分钟只记录一次,其余只计数。每个账户每个 UTC 日最多记录一定数量的请求(默认 100,000 条),超出的部分只计数、不记录。需要 tenant_admin,且 Key 未限定 Space 或元数据范围。需要 knowledge:manage。
需要的能力 knowledge:manage
指南:检索与上下文
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
cursor | 查询 | DevCursor | 上一页的 next_cursor。不传则从第一页开始。长度 1 到 1024 |
limit | 查询 | integer | 每页最多返回的条目数:1 到 100,默认 20。1 到 100,默认 20 |
status_class | 查询 | 2xx | 3xx | 4xx | 5xx | 只返回该状态码类别的响应。 |
route | 查询 | string | 只返回该路由的请求,写法与 route 相同,例如 POST /v2/retrieval/search。 |
key_id | 查询 | DevId | 只返回用该 Key 发出的请求。长度 1 到 256 |
error_code | 查询 | string | 只返回结果为该错误码的请求。 |
client | 查询 | DevRequestClient | 只返回来自该客户端的请求。 |
auth | 查询 | api_key | console | token | 只返回用该凭据发出的请求:api_key 不包括控制台自身的请求。 |
since | 查询 | string (date-time) | 只返回在该时间或之后到达的请求。 |
until | 查询 | string (date-time) | 只返回在该时间之前到达的请求。 |
request_id | 查询 | string | X-Request-Id 为该值的请求。 |
trace_id | 查询 | string | 带有该轨迹 id 或包 id 的请求。 |
响应
200application/jsonDevRequestLogPage
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/request-logs" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"data": [
{
"id": "<id>",
"created_at": "2026-11-06T00:00:00Z",
"method": "GET",
"route": "<route>",
"status": 1,
"duration_ms": 1,
"auth": "api_key",
"principal_id": "<principal_id>",
"request_id": "<request_id>",
"client": "sdk-typescript"
}
],
"retention_days": 1
}读取请求日志
GET/v2/request-logs/{log_id}
一条请求日志。超过保留期后返回 404 not_found。需要 tenant_admin,且 Key 未限定 Space 或元数据范围。需要 knowledge:manage。
需要的能力 knowledge:manage
参数
响应
200application/jsonDevRequestLog
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/request-logs/$LOG_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"id": "rql_7f3a91c2d4e5b6a7",
"created_at": "2026-11-17T08:02:00.123456Z",
"method": "POST",
"route": "POST /v2/retrieval/search",
"status": 200,
"duration_ms": 182,
"auth": "api_key",
"principal_id": "principal-alice",
"key_id": "key_01JD2M7Q",
"key_name": "Production",
"key_prefix": "mb_live_3f9a",
"request_id": "req_01JD2M7Q",
"trace_id": "trc_01JD2M7R",
"client": "sdk-typescript",
"client_version": "0.2.0"
}读取检索轨迹
GET/v2/retrieval/traces/{trace_id}
按 trace_id 或 pack_id 读取一次搜索、上下文或回答调用的记录:返回的内容、候选数、各阶段耗时和路由决策。搜索的轨迹包含查询文本。候选数只统计发起该次搜索的调用方能读取的内容。持有 knowledge:manage 的 tenant_admin 可读取账户的全部轨迹,并能看到各阶段的耗时;其他调用方只能读取自己主体的轨迹,不含各阶段耗时,读取其他主体的轨迹返回 404 not_found。限定了 Space 或元数据范围的 Key 不能读取轨迹。需要 knowledge:read。
需要的能力 knowledge:read
指南:检索与上下文
参数
响应
200application/jsonDevRetrievalTrace
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/retrieval/traces/$TRACE_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"id": "<id>",
"kind": "search",
"created_at": "2026-11-06T00:00:00Z",
"citations": [
{
"entry_id": "<entry_id>",
"version_id": "<version_id>"
}
],
"summary": {}
}