# Usage

Metered usage per Space and the limits this deployment enforces.

API reference. Base URL: `https://api.mirabase.dev`

## Read limits

`GET /v2/limits`

The limits that apply to this account: this deployment's figures, lowered to the plan's where the plan sets one (`plan`). `tenant_requests_per_minute_*` and `tenant_retrieval_concurrency` are the account-wide totals on top of each key's own figures. Over a stored quota the API returns 429 `quota_exceeded` with `quota` naming it. Needs no capability: any valid key can read them.

**Capability** No capability is checked.

Guide: [API conventions](https://mirabase.io/developers/conventions.md#rate-limits)

### Responses

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

### Error statuses

`400` `401` `403` `404` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
curl "https://api.mirabase.dev/v2/limits" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### Example response

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

## Read the processing queue

`GET /v2/queue`

Your account's processing queue: how many jobs wait and run, whether processing is paused, the oldest wait, an estimate of how long the due jobs need, and the limit on queued jobs that make content searchable, past which writes get 429 `ingest_backlog`. Requires `tenant_admin` and a key without Space or metadata restrictions (403 `forbidden` otherwise). Needs `knowledge:read`.

**Capability** `knowledge:read`

Guide: [Processing status](https://mirabase.io/developers/processing.md#backlog)

### Responses

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

### Error statuses

`400` `401` `403` `404` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
curl "https://api.mirabase.dev/v2/queue" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### Example response

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

## Read usage

`GET /v2/usage`

Metered usage per visible Space, ordered by Space id, then metric. A `tenant_admin` key without Space restrictions also gets `tenant_totals` on the first page. Needs `knowledge:read`.

**Capability** `knowledge:read`

Guide: [API conventions](https://mirabase.io/developers/conventions.md#behavior-changes)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | Query | `DevCursor` | Optional | The `next_cursor` of the previous page. Omit it to start from the first page. length 1..1024 |
| `limit` | Query | `integer` | Optional | How many items a page holds at most: 1 to 100, 20 by default. 1..100, default: 20 |

### Responses

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

### Error statuses

`400` `401` `403` `404` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
curl "https://api.mirabase.dev/v2/usage" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### Example response

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