Read Topology
read_topologyRead current work, a particular work item, or historical trails.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Paging — max entries to return (default 20, max 100). Ignored unless trail is set. | |
| trail | No | Trail paging (topology 3.0) — when set, returns { container_id, trail, entries, has_more, warnings? } from the did trail (the client-written narrative: ts, text, work_ref?, by?) or the ops audit (worker-only: ts, action, ref?, detail?), every action included. Newest-first; pair with before/limit to walk deeper — retention is keep-everything, so the full history is reachable. On trail='ops', include_actions / exclude_actions narrow the window. | |
| before | No | Paging — ISO timestamp; only entries with ts < before are returned. Pair with limit. Ignored unless trail is set. | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| work_item | No | Work-item paging — when set, finds the work item by `what` across all four groups (active/paused/blocked/done) and returns { container_id, work_item: { group, item } } (plus warnings when an ops-trail action filter is set without trail='ops') with the full item including state/next, all annotations, refs, and group-specific fields. Use to revive a paused thread when boot trim hid the item's full context. Returns an error if no item with the given `what` exists. Takes precedence over trail when both are set. | |
| projection | No | Read grain (topology 3.0). 'full' (default): the complete state row (work + scalars — work items carry state/next) plus the did tail (12) and ops tail (10) from their tables, newest-first; the ops tail leaves out the reads (knowledge_read, knowledge_describe, knowledge_validate, reground_called). 'summary': the hot multi-window handoff read — work headers with per-group counts + the did tail, no ops. Ignored when trail or work_item is set (those keep their own focused shapes). | |
| container_id | Yes | Container ID — without trail or work_item, returns { projection, state } (see projection), plus warnings when an ops-trail action filter is set without trail='ops'. worker_meta is not returned (platform-internal). | |
| exclude_actions | No | Ops-trail filter: leave out these actions (exact names or a prefix ending in *). With include_actions, the result is include minus exclude. Applies to trail='ops' only; elsewhere it is ignored with a warning. | |
| include_actions | No | Ops-trail filter: return only these actions. Each entry is an exact action name or a prefix ending in * (e.g. 'signal_*'). Unknown names are dropped with a warning; if nothing is left, no entries are returned. Applies to trail='ops' only; elsewhere it is ignored with a warning. |