# 请求日志

账户最近的 API 请求和检索调用的轨迹。

API 参考。Base URL：`https://api.mirabase.dev`

## 列出请求日志

`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`

指南：[检索与上下文](https://mirabase.io/zh/developers/retrieval.md#inspect)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `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`](https://mirabase.io/zh/developers/api/retrieval.md#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 的请求。 |

### 响应

- `200` `application/json` `DevRequestLogPage`

### 错误状态

`400` `401` `403` `404` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
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 |

### 响应

- `200` `application/json` `DevRequestLog`

### 错误状态

`400` `401` `403` `404` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
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`

指南：[检索与上下文](https://mirabase.io/zh/developers/retrieval.md#inspect)

### 参数

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

### 响应

- `200` `application/json` `DevRetrievalTrace`

### 错误状态

`400` `401` `403` `404` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
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": {}
}
```
