Skip to content
Developer docs
Docs menu

Request logs

Markdown

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

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

Parameters

NameInTypeDescription
cursorQueryDevCursorThe next_cursor of the previous page. Omit it to start from the first page.length 1..1024
limitQueryintegerHow many items a page holds at most: 1 to 100, 20 by default.1..100, default: 20
status_classQuery2xx | 3xx | 4xx | 5xxOnly responses in this class.
routeQuerystringOnly this route, as written in route: POST /v2/retrieval/search.
key_idQueryDevIdOnly requests made with this key.length 1..256
error_codeQuerystringOnly requests that returned this error code.
clientQueryDevRequestClientOnly requests from this client.
authQueryapi_key | console | tokenOnly requests made with this credential: api_key leaves out the console's own requests.
sinceQuerystring (date-time)Only requests that arrived at or after this time.
untilQuerystring (date-time)Only requests that arrived before this time.
request_idQuerystringThe request with this X-Request-Id.
trace_idQuerystringThe requests with this trace or pack id.

Responses

Error statuses

400 401 403 404 422 429 500 503 See Errors for the error shape and Error codes for what each code means.

Example request

curl
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

NameInTypeDescription
log_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256

Responses

Error statuses

400 401 403 404 422 429 500 503 See Errors for the error shape and Error codes for what each code means.

Example request

curl
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

Parameters

NameInTypeDescription
trace_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256

Responses

Error statuses

400 401 403 404 422 429 500 503 See Errors for the error shape and Error codes for what each code means.

Example request

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