# 用量

各 Space 的计量用量，以及当前部署实际执行的限制。

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

## 读取限制

`GET /v2/limits`

适用于本账户的限制：取当前部署的数值；套餐（`plan`）设有某项数值时，下调为套餐的数值。`tenant_requests_per_minute_*` 和 `tenant_retrieval_concurrency` 是在每个 Key 自身限额之外另设的账户总上限。持久配额用尽时，API 返回 429 `quota_exceeded`，由 `quota` 指明是哪一项。不需要任何能力：任何有效的 Key 都可以读取。

**需要的能力** 不检查能力。

指南：[API 约定](https://mirabase.io/zh/developers/conventions.md#rate-limits)

### 响应

- `200` `application/json` `DevLimits`

### 错误状态

`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/limits" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### 响应结构示例

```json
{
  "data": [
    {
      "name": "research",
      "value": 1
    }
  ]
}
```

## 读取处理队列

`GET /v2/queue`

账户的处理队列：等待和运行中的任务数、处理是否已暂停、最长的等待时间、就绪任务预计所需的时间，以及使内容可检索的排队任务上限（超过后写入返回 429 `ingest_backlog`）。需要 `tenant_admin`，且 Key 未限定 Space 或元数据范围（否则返回 403 `forbidden`）。需要 `knowledge:read`。

**需要的能力** `knowledge:read`

指南：[处理进度](https://mirabase.io/zh/developers/processing.md#backlog)

### 响应

- `200` `application/json` `DevAccountQueue`

### 错误状态

`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/queue" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### 响应结构示例

```json
{
  "queued": 1240,
  "due": 1180,
  "delayed": 60,
  "running": 4,
  "paused": false,
  "oldest_queued_seconds": 95,
  "eta_seconds": 840,
  "limit": 10000,
  "as_of": "2026-11-17T09:00:00Z"
}
```

## 读取用量

`GET /v2/usage`

各可见 Space 的计量用量，依次按 Space id 和指标排序。不受 Space 限制的 `tenant_admin` Key 还会在第一页获得 `tenant_totals`。需要 `knowledge:read`。

**需要的能力** `knowledge:read`

指南：[API 约定](https://mirabase.io/zh/developers/conventions.md#behavior-changes)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `cursor` | 查询 | `DevCursor` | 可选 | 上一页的 `next_cursor`。不传则从第一页开始。 长度 1 到 1024 |
| `limit` | 查询 | `integer` | 可选 | 每页最多返回的条目数：1 到 100，默认 20。 1 到 100，默认 20 |

### 响应

- `200` `application/json` `DevUsagePage`

### 错误状态

`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/usage" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### 响应结构示例

```json
{
  "data": [
    {
      "metric": "writes",
      "window_start": "2026-11-06T00:00:00Z",
      "used": 1,
      "space_id": "<space_id>"
    }
  ]
}
```
