跳到主要内容
开发者文档
文档目录

请求日志

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查询stringX-Request-Id 为该值的请求。
trace_id查询string带有该轨迹 id 或包 id 的请求。

响应

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/request-logs" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

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

参数

名称位置类型说明
log_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256

响应

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/request-logs/$LOG_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

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

指南:检索与上下文

参数

名称位置类型说明
trace_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256

响应

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/retrieval/traces/$TRACE_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "id": "<id>",
  "kind": "search",
  "created_at": "2026-11-06T00:00:00Z",
  "citations": [
    {
      "entry_id": "<entry_id>",
      "version_id": "<version_id>"
    }
  ],
  "summary": {}
}