Skip to content
Developer docs
Docs menu

Processing status

Markdown

A file becomes searchable first, and memories are built afterwards: wait for a single file, track a bulk import, and check whether content is still being processed.

After a write, the service extracts the text, indexes it, and publishes it to search, in that order. Once these three steps are done, the file can be found by meaning; relations, classification, summaries, and memories are produced afterwards and do not hold up search. Text of up to 64 KiB sent in the request body can be found by its words right after the write; see Retrieval.

The stage of the latest version is in stage: once it is enriching or ready, search finds that version.

Wait until a file is searchable

GET /v2/entries/{entry_id}/processing returns the stage and progress of the latest version, and, while it is queued, queue with the number of jobs ahead of it and the reason it is waiting. The SDKs' entries.waitUntil (entries.wait_until in Python) polls this endpoint for you. By default, it waits until the file is searchable; with until: "ready", it waits until all processing steps complete.

curl
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/processing" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
  • When processing fails, waitUntil returns the last status instead of throwing: check error. Retry a failed version with POST /v2/entries/{entry_id}/reprocess.
  • When the wait times out (10 minutes by default), the SDK throws an error with code wait_timeout; processing continues on the server.
  • For a single write, you can send Prefer: wait with the request instead; see Write a file.

Follow a bulk import

For a bulk import, you do not need to poll every Entry individually. GET /v2/spaces/{space_id}/processing counts the Entries in a Space by stage and returns the rate at which they become searchable and the estimated time remaining. The SDKs' spaces.waitUntil (spaces.wait_until in Python) polls this endpoint until every Entry in the Space is searchable; onProgress receives each status summary to update a progress display.

curl
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/processing" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
  • Failed Entries are counted in counts.failed; check the cause with GET /v2/entries/{entry_id}/processing.
  • Memories are distilled separately after a file is searchable, and memory reports the distillations still queued or running. An Entry that waits only for distillation counts as searchable. To wait for memories as well, pass until: "ready".
  • Work from different Spaces and accounts takes turns, so a large import in one Space does not hold up new files in another.

Check for content still being processed

When Entries in the searched Spaces are still being processed, the responses of search, context, and answer include pending_processing, where entries is the number of Entries that are not yet searchable. Their content may be missing from the results: if the content you need might be among them, query again shortly or wait for processing to finish first.

json
{
  "pack_id": "pck_...",
  "items": [
    "..."
  ],
  "pending_processing": {
    "entries": 12
  }
}

The SDKs' context and answer return this field as is; search returns the array of hits and carries the field as the array's pendingProcessing property (pending_processing in Python). The results of the MCP tool mira.search also include pending_processing.

When the processing queue is full

When the number of queued jobs for an account exceeds its limit, writes return 429 ingest_backlog: queue gives the number of queued jobs and the estimated wait time, and Retry-After is 30 to 600 seconds. Wait for Retry-After before retrying. The SDKs wait and retry automatically only when Retry-After is no longer than maxRetryAfterMs (max_retry_after in Python, 60 seconds by default); above that they throw MirabaseRateLimitError, so read retryAfterSeconds (retry_after_seconds in Python) and wait yourself, or raise the option (see Retries and idempotency). An account admin can inspect the queue at any time with GET /v2/queue.

Next steps