# Processing status

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](https://mirabase.io/developers/retrieval.md#search).

The stage of the latest version is in [stage](https://mirabase.io/developers/api/schemas.md#DevEntryProcessing.stage): once it is `enriching` or `ready`, search finds that version.

## Wait until a file is searchable

[`GET /v2/entries/{entry_id}/processing`](https://mirabase.io/developers/api/entries.md#entries-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:

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

TypeScript:

```ts
// Returns once search finds the file ("enriching" or "ready"), or when it failed.
const status = await mirabase.entries.waitUntil({ path: "/notes/launch.md" }, {
  onProgress: (s) => console.log(s.stage, `${s.progress.done}/${s.progress.total}`),
});
if (status.stage === "failed") console.log(status.error?.code);
```

Python:

```python
# Returns once search finds the file ("enriching" or "ready"), or when it failed.
status = mb.entries.wait_until(
    {"path": "/notes/launch.md"},
    on_progress=lambda s: print(s["stage"], f"{s['progress']['done']}/{s['progress']['total']}"),
)
if status["stage"] == "failed":
    print(status["error"]["code"])
```

- When processing fails, `waitUntil` returns the last status instead of throwing: check `error`. Retry a failed version with [`POST /v2/entries/{entry_id}/reprocess`](https://mirabase.io/developers/api/entries.md#entries-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](https://mirabase.io/developers/files.md#write).

## Follow a bulk import

For a bulk import, you do not need to poll every Entry individually. [`GET /v2/spaces/{space_id}/processing`](https://mirabase.io/developers/api/spaces.md#spaces-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:

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

TypeScript:

```ts
// Waits until every Entry in the Space is searchable; failed Entries count as finished.
const summary = await mirabase.spaces.waitUntil({
  onProgress: ({ counts, eta_seconds }) => console.log(counts, eta_seconds),
});
console.log(`${summary.counts.failed} failed`);
```

Python:

```python
# Waits until every Entry in the Space is searchable; failed Entries count as finished.
summary = mb.spaces.wait_until(
    on_progress=lambda s: print(s["counts"], s.get("eta_seconds")),
)
print(summary["counts"]["failed"], "failed")
```

- Failed Entries are counted in `counts.failed`; check the cause with [`GET /v2/entries/{entry_id}/processing`](https://mirabase.io/developers/api/entries.md#entries-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](https://mirabase.io/developers/sdks.md#retries)). An account admin can inspect the queue at any time with [`GET /v2/queue`](https://mirabase.io/developers/api/usage.md#usage-queue).

## Next steps

- [Files and versions](https://mirabase.io/developers/files.md): write, read, and edit files.
- [Retrieval and context](https://mirabase.io/developers/retrieval.md): retrieve from what has been processed.
- [API reference](https://mirabase.io/developers/api/spaces.md#spaces-processing): all fields of the processing status response.
