# Request logs

The account's recent API requests and the traces of retrieval calls.

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

## List request logs

`GET /v2/request-logs`

Recent API requests of the account, newest first: method, route, status, error code, latency, key, principal, request id, trace id and client. Metadata only. Kept for `retention_days` days (14 by default; the deployment can set 1 to 90). Requests appear within about a second. Responses with status 429 are logged once per key (or principal), route and minute; the rest are only counted. An account logs at most a set number of requests per UTC day (100,000 by default); requests past it are counted, not logged. Requires `tenant_admin`, and a key without Space or metadata restrictions. Needs `knowledge:manage`.

**Capability** `knowledge:manage`

Guide: [Retrieval and context](https://mirabase.io/developers/retrieval.md#inspect)

### 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 |
| `status_class` | Query | `2xx \| 3xx \| 4xx \| 5xx` | Optional | Only responses in this class. |
| `route` | Query | `string` | Optional | Only this route, as written in `route`: [`POST /v2/retrieval/search`](https://mirabase.io/developers/api/retrieval.md#retrieval-search). |
| `key_id` | Query | `DevId` | Optional | Only requests made with this key. length 1..256 |
| `error_code` | Query | `string` | Optional | Only requests that returned this error code. |
| `client` | Query | `DevRequestClient` | Optional | Only requests from this client. |
| `auth` | Query | `api_key \| console \| token` | Optional | Only requests made with this credential: `api_key` leaves out the console's own requests. |
| `since` | Query | `string (date-time)` | Optional | Only requests that arrived at or after this time. |
| `until` | Query | `string (date-time)` | Optional | Only requests that arrived before this time. |
| `request_id` | Query | `string` | Optional | The request with this `X-Request-Id`. |
| `trace_id` | Query | `string` | Optional | The requests with this trace or pack id. |

### Responses

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

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

### Example response

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

## Read a request log

`GET /v2/request-logs/{log_id}`

One request log. 404 `not_found` once it is past the retention period. Requires `tenant_admin`, and a key without Space or metadata restrictions. Needs `knowledge:manage`.

**Capability** `knowledge:manage`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `log_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |

### Responses

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

### 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/request-logs/$LOG_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### Example response

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

## Read a retrieval trace

`GET /v2/retrieval/traces/{trace_id}`

What a search, context or answer call recorded, by its `trace_id` or `pack_id`: what it returned, candidate counts, stage times and the routing decision. A search trace includes its query. Candidate counts cover only what the caller of that search could read. A `tenant_admin` with `knowledge:manage` reads every trace of the account and sees how long each stage took; anyone else reads only the traces of their own principal, without stage times, and another principal's trace is 404 `not_found`. A key with Space or metadata restrictions cannot read traces. Needs `knowledge:read`.

**Capability** `knowledge:read`

Guide: [Retrieval and context](https://mirabase.io/developers/retrieval.md#inspect)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `trace_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |

### Responses

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

### 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/retrieval/traces/$TRACE_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### Example response

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