GET /v1/derivation/status
How far behind a scope's async derived layers are — a catch-up probe for episodes, beliefs, and concepts.
Authorization
bearer PASETO v4 public token (or deployment gate key). Auth-disabled dev instances accept any caller.
In: header
Query Parameters
Scope path to report on
Response Body
application/json
application/json
curl -X GET "https://example.com/v1/derivation/status?scope=string"{ "scope": "string", "caught_up": true, "dirty": true, "idle_seconds": 0, "last_write_at": "2019-08-24T14:15:22Z", "last_built_at": "2019-08-24T14:15:22Z", "last_tick_at": "2019-08-24T14:15:22Z", "built": { "episodes": 0, "beliefs": 0, "concepts": 0, "errors": 0 }}What it answers
Writes return 202 captured and the derived layers (episodes, beliefs,
concepts) are built asynchronously by a background scheduler. /v1/derivation/status?scope=<scope>
tells you whether that catch-up has finished for a scope — the read-your-derived-writes probe.
The response (DerivationStatus) is flat:
| Field | Meaning |
|---|---|
scope | The scope you asked about. |
caught_up | true only when a write has happened, nothing is queued, ingest has been idle ~60 s, and the scheduler rebuilt after the last write. |
dirty | Work is currently queued for this scope. |
idle_seconds | Seconds since the last write to the scope (null if never written). |
last_write_at / last_built_at / last_tick_at | Timestamps of the last write, last successful build, and last scheduler tick (null until they occur). |
built | Counts produced so far: { episodes, beliefs, concepts, errors }. |
scope is a required query parameter — omitting it returns 422 with missing field "scope".
Use it to gate reads after bulk ingest
After a batch import or a burst of writes, poll until caught_up: true (or dirty: false with an
idle_seconds past your threshold) before relying on the Facts/Beliefs/Understanding layers or on
order-sensitive recall. For a single event, prefer ?wait=indexed on the
write instead of polling here.
built stays 0 without enrichment
built.beliefs / built.concepts only advance when the LLM-derived layers are enabled — verified live
on a content-only instance, built stays { episodes: 0, beliefs: 0, concepts: 0, errors: 0 } because
enrichment is off by default. caught_up still reflects the scheduler state regardless. See
Self-hosting defaults.