--- title: "List Dream Pass Records" method: GET path: "/api/admin/memory/{user_id}/dream/passes" tags: ["v2", "admin", "memory"] --- # List Dream Pass Records `GET /api/admin/memory/{user_id}/dream/passes` ## Request - The document declares no server URL. - Auth: HTTP bearer List a user's dream passes, across the account and every expert, newest first: the durable records, each as ``GET .../record`` returns it. A finished pass keeps its phase outputs, operations and usage; its input bundle went when it closed, and its lease with it, or, for a pass whose close left a cleanup pending, once that cleanup finished. ## Path parameters - `user_id` string, required: User id or 'me' ## Query parameters - `status` 'open' | 'all': Only the passes still running, or all of them - `limit` integer: How many passes, newest first ## Response `200` Successful Response - DreamPassListResponse: A user's dream passes, every scope, newest first. - `passes` PublicDreamPassRecord[], required - `id` string, required - `user_id` string, required - `expert_id` string, nullable, required - `scope_key` string, required - `route` 'SYNC' | 'ANTHROPIC_BATCH', required - `trigger` 'CRON' | 'ADMIN' | 'EVAL', required - `phase` 'GATHER' | 'CONSOLIDATE' | 'RECOMBINE' | 'SANITIZE' | 'APPLY' | 'DONE', required - `status` 'QUEUED' | 'RUNNING' | 'SUBMITTED' | 'APPLYING' | 'COMPLETE' | 'ERRORED' | 'CANCELLED' | 'EXPIRED' | 'SKIPPED', required - `skip_reason` string, nullable, required - `cancel_generation` integer, required - `provider_batch_id` string, nullable, required - `lease_expires_at` string, date-time, nullable, required - `cleanup_pending_at` string, date-time, nullable - `cost_context` object, nullable - `input_bundle` DreamInput, required: The whole gather-step bundle handed to the phase 1 prompt. - `user_id` string, required - `expert_id` string, nullable - `group_id` string, required - `window_start` string, date-time, required - `window_end` string, date-time, required - `episodes` EpisodeRow[] - `uuid` string, required - `name` string, nullable, required - `content` string, nullable, required - `source_description` string, nullable, required - `valid_at` string, nullable, required - `created_at` string, nullable, required - `facts` FactRow[] - `uuid` string, required - `recall_count` integer, nullable - `last_recalled_at` string, nullable - `prev_recalled_at` string, nullable - `source` string, nullable, required - `target` string, nullable, required - `name` string, nullable, required - `fact` string, nullable, required - `scope` string, nullable, required - `confidence` number, nullable, required - `status` string, nullable, required - `created_at` string, nullable, required - `recent_sessions` SessionRow[] - `session_id` string, required - `title` string, nullable, required - `created_at` string, date-time, nullable, required - `body` string, required - `known_fact_uuids` string[] - `known_episode_uuids` string[] - `phase_outputs` DreamPhaseOutputs, required: Each phase's validated output, as the next phase and apply read it. - `consolidate` ConsolidationOutput - `facts` ConsolidatedFact[] - `content` string, required: Canonical statement of the consolidated fact. - `scope` string: Memory scope namespace, e.g. 'real:global' or 'project:foo'. - `confidence` number, required: Phase 1 model's confidence in the consolidated statement. - `source_episode_uuids` string[]: UUIDs of the :Episodic nodes the fact was consolidated from. - `source_fact_uuids` string[]: UUIDs of the active facts (:RELATES_TO edges) the fact was consolidated from. - `recombine` RecombinationOutput - `proposals` ProposedFinding[] - `content` string, required: The proposed finding. - `scope` string: Memory scope. - `memory_kind` 'fact' | 'preference' | 'rule' | 'finding' | 'plan' | 'event' | 'procedure' - `confidence` number, required: Phase 2 model's self-rated confidence. - `rationale` string, required: Why the dream pass proposes this — recorded for audit. - `source_episode_uuids` string[] - `source_fact_uuids` string[] - `sanitize` DreamOperations: Phase 3 output — what apply.py writes back to the world. Guardrails enforced by phase 3's prompt and double-checked in apply.py: * ≤ ``max_demotions_per_pass`` demotions per pass (runaway-demotion mitigation per spec §3 / TODO P0.3b). * Scope match enforced — a write or proposal citing a fact of another scope (a fact's scope, else ``real:global``) is dropped whole, as is one citing nothing the pass read (``dream/citations.py``); episode citations are not scoped. A source in the same scope that the write does not truly rest on is not caught. * Empty ``writes`` and ``proposals`` is fine; a pass can be no-op. - `writes` ConsolidatedFact[]: Phase 1 consolidated facts that survived the sanitizer. - `content` string, required: Canonical statement of the consolidated fact. - `scope` string: Memory scope namespace, e.g. 'real:global' or 'project:foo'. - `confidence` number, required: Phase 1 model's confidence in the consolidated statement. - `source_episode_uuids` string[]: UUIDs of the :Episodic nodes the fact was consolidated from. - `source_fact_uuids` string[]: UUIDs of the active facts (:RELATES_TO edges) the fact was consolidated from. - `proposals` ProposedFinding[]: Phase 2 proposals that survived the sanitizer. - `content` string, required: The proposed finding. - `scope` string: Memory scope. - `memory_kind` 'fact' | 'preference' | 'rule' | 'finding' | 'plan' | 'event' | 'procedure' - `confidence` number, required: Phase 2 model's self-rated confidence. - `rationale` string, required: Why the dream pass proposes this — recorded for audit. - `source_episode_uuids` string[] - `source_fact_uuids` string[] - `demotions` DreamDemotion[] - `edge_uuid` string, required: UUID of the :RELATES_TO edge to demote. - `reason` string, required: Short reason recorded on the edge. Examples: 'stale_fact', 'contradicted_by:{uuid}', 'entity_invalidated:{uuid}', 'user_signal', 'unratified', 'web_contradicted:{url}'. - `new_status` 'superseded' | 'contradicted' - `entity_invalidations` EntityInvalidation[] - `entity_uuid` string, required - `reason` string, required - `summary_for_user` string: Short narrative for the dream-kind ChatSession body. - `operations` DreamPassOperations, required: The clamped operations apply was handed, then what it reported. - `planned` DreamOperations: Phase 3 output — what apply.py writes back to the world. Guardrails enforced by phase 3's prompt and double-checked in apply.py: * ≤ ``max_demotions_per_pass`` demotions per pass (runaway-demotion mitigation per spec §3 / TODO P0.3b). * Scope match enforced — a write or proposal citing a fact of another scope (a fact's scope, else ``real:global``) is dropped whole, as is one citing nothing the pass read (``dream/citations.py``); episode citations are not scoped. A source in the same scope that the write does not truly rest on is not caught. * Empty ``writes`` and ``proposals`` is fine; a pass can be no-op. - `writes` ConsolidatedFact[]: Phase 1 consolidated facts that survived the sanitizer. - `content` string, required: Canonical statement of the consolidated fact. - `scope` string: Memory scope namespace, e.g. 'real:global' or 'project:foo'. - `confidence` number, required: Phase 1 model's confidence in the consolidated statement. - `source_episode_uuids` string[]: UUIDs of the :Episodic nodes the fact was consolidated from. - `source_fact_uuids` string[]: UUIDs of the active facts (:RELATES_TO edges) the fact was consolidated from. - `proposals` ProposedFinding[]: Phase 2 proposals that survived the sanitizer. - `content` string, required: The proposed finding. - `scope` string: Memory scope. - `memory_kind` 'fact' | 'preference' | 'rule' | 'finding' | 'plan' | 'event' | 'procedure' - `confidence` number, required: Phase 2 model's self-rated confidence. - `rationale` string, required: Why the dream pass proposes this — recorded for audit. - `source_episode_uuids` string[] - `source_fact_uuids` string[] - `demotions` DreamDemotion[] - `edge_uuid` string, required: UUID of the :RELATES_TO edge to demote. - `reason` string, required: Short reason recorded on the edge. Examples: 'stale_fact', 'contradicted_by:{uuid}', 'entity_invalidated:{uuid}', 'user_signal', 'unratified', 'web_contradicted:{url}'. - `new_status` 'superseded' | 'contradicted' - `entity_invalidations` EntityInvalidation[] - `entity_uuid` string, required - `reason` string, required - `summary_for_user` string: Short narrative for the dream-kind ChatSession body. - `applied` DreamPassApplied: What apply reported: the counts and narrative a ``DreamPassResult`` carries, and the per-operation snapshot. - `consolidated_count` integer - `proposal_count` integer - `demotion_count` integer - `entity_invalidation_count` integer - `dropped_forgotten` integer - `pending_writes` integer - `failed_writes` integer - `provenance_pending` integer - `uncited_writes_dropped` integer - `cross_scope_citations_dropped` integer - `protected_demotions` integer - `indeterminate_demotion_writes` integer - `demotion_accounting_complete` boolean - `summary_for_user` string - `dream_session_id` string, nullable - `ingestion_drain_status` 'not_applied' | 'unknown' | 'drained' | 'skipped' | 'timed_out': Fate of a dream pass's enqueued graph writes at the moment the pass was reported complete. Five distinct states, so consumers (and a future Memory Visualizer) can tell a healthy by-design skip from a real failure: * ``drained`` — the worker finished every one of the pass's own episodes before the pass returned (sync path): each was written, dropped for resting on a forget (``dropped_forgotten``), or failed with a logged error; or the pass enqueued nothing to drain. Healthy. * ``skipped`` — the drain was intentionally not run to avoid stalling a shared serial loop (batch path). The episodes process fire-and-forget, counted pending; healthy by design, NOT a failure signal. * ``not_applied`` — this pass never began applying, so no drain ran. * ``unknown`` — this pass began applying but recorded no outcome: it may still be applying, or have applied before it ended (a cancel after its last check does not stop an apply), or failed partway. Its writes may have been enqueued, so whether they drained is not known. * ``timed_out`` — the sync-path drain was attempted but did not finish within its budget. The episodes not written yet are counted pending, not written; they stay queued in-process, and are lost if the worker's pod restarts. This is the only value that warrants an operator warning. - `snapshot` DreamOperationsSnapshot: Detailed per-operation rollup of a single dream pass. Shape used by three downstream consumers: 1. The admin memory-visualizer UI (renders the per-edge detail). 2. AgentProbe eval scorers (read via ``rawExchangeKey``). 3. The future chat-stream ``dream.operations`` SSE event (P6 + P9 daydreaming, see ``dream/TODO.md``). Kept additive on ``DreamPassResult`` so adding fields here doesn't bump the count-only top-level columns existing clients rely on. - `writes` WriteSummary[] - `edge_uuid` string, nullable - `content` string, required - `scope` string - `confidence` number, nullable - `status` 'active' | 'tentative' - `source_episode_uuids` string[] - `source_fact_uuids` string[] - `proposals` WriteSummary[] - `edge_uuid` string, nullable - `content` string, required - `scope` string - `confidence` number, nullable - `status` 'active' | 'tentative' - `source_episode_uuids` string[] - `source_fact_uuids` string[] - `demotions` DemotionSummary[] - `edge_uuid` string, required - `reason` string, required - `new_status` 'superseded' | 'contradicted', required - `applied` boolean - `protected` boolean - `indeterminate` boolean - `entity_invalidations` EntityInvalidationSummary[] - `entity_uuid` string, required - `reason` string, required - `edges_touched` string[] - `edges_protected` string[] - `indeterminate` boolean - `usage` DreamPassUsage, required: Aggregate usage across all phases of one dream pass. Surfaced on ``DreamPassResult.usage`` so eval / admin UI / billing can read tokens + cost without recomputing. Written to ``PlatformCostLog`` from apply.py with ``provider='dream_pass'``; charged against the user's rate-limit window via ``persist_and_record_usage`` so dream-pass spend rolls into the same daily/weekly subscription tier budget as chat-execution overage. - `phases` PhaseUsage[] - `phase` 'consolidate' | 'recombine' | 'sanitize', required - `model` string, required - `input_tokens` integer - `output_tokens` integer - `cache_read_tokens` integer - `cache_creation_tokens` integer - `cost_usd` number, nullable - `total_input_tokens` integer - `total_output_tokens` integer - `total_cache_read_tokens` integer - `total_cache_creation_tokens` integer - `total_cost_usd` number, nullable - `discount_applied` number - `window_start` string, date-time, nullable, required - `window_end` string, date-time, nullable, required - `error` string, nullable, required - `erased_at` string, date-time, nullable - `read_uuids` string[] - `created_at` string, date-time, required - `started_at` string, date-time, nullable, required - `submitted_at` string, date-time, nullable, required - `applied_at` string, date-time, nullable, required - `completed_at` string, date-time, nullable, required - `updated_at` string, date-time, required ## Other responses - `401`: Authentication required - `422`: Validation Error ## Changes - **2026-10-22** `48ad8f0dd980`: 1 breaking, 2 warning - removed the required property `passes/items/lease_token` from the response with the `200` status - added the new `not_applied` enum value to the `passes/items/operations/applied/anyOf[subschema #1: DreamPassApplied]/ingestion_drain_status` response property for the response status `200` - added the new `unknown` enum value to the `passes/items/operations/applied/anyOf[subschema #1: DreamPassApplied]/ingestion_drain_status` response property for the response status `200` - **2026-10-20** `270f7e615e6e`: 8 info - added the optional property `passes/items/erased_at` to the response with the `200` status - added the optional property `passes/items/operations/applied/anyOf[subschema #1: DreamPassApplied]/cross_scope_citations_dropped` to the response with the `200` status - added the optional property `passes/items/operations/applied/anyOf[subschema #1: DreamPassApplied]/provenance_pending` to the response with the `200` status - added the optional property `passes/items/operations/applied/anyOf[subschema #1: DreamPassApplied]/uncited_writes_dropped` to the response with the `200` status - …4 more - …earlier changes not shown [Operation history](https://skmtc.dev/significant-gravitas/apis/autogpt-agent-server/changes/api/admin/memory/:user_id/dream/passes/get.md) --- [API](https://skmtc.dev/significant-gravitas/apis/autogpt-agent-server.md) - [All operations](https://skmtc.dev/significant-gravitas/apis/autogpt-agent-server/llms.txt) - [OpenAPI document](https://skmtc.dev/significant-gravitas/apis/autogpt-agent-server/revisions/c508818c16ad?raw)