The whole hunk
from line 7, old and new numbered
/
lines
from line 7
77
88**GET** `/v1/dreams/{dream_id}`
99
10Get a Dream
10Get a dream by ID to check its status, output memory store, and token usage.
1111
12Archived dreams are returned too.
13
14See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#track-progress) for how to poll a dream and what each status means.
15
1216## Path parameters
1317
1418- `dream_id: string`
1519
20 The ID of the dream to get (`drm_...`).
21
1622## Headers
1723
1824- `"anthropic-beta": optional array of AnthropicBeta`
from line 123
117123
118124- `"anthropic-workspace-id": optional string`
119125
126 Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`).
127
128 Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.
129
120130## Returns
121131
122132- `BetaDream object`
123133
124 An asynchronous memory-consolidation job that reads a memory store plus a set of session transcripts and writes consolidated memories into an output memory store — a new store by default, or an existing store chosen via output_behavior. The Dreams API is in research preview: the request and response shapes are volatile and may change without the deprecation period that applies to generally-available endpoints.
134 An asynchronous job that reads a memory store and past sessions, then writes a reorganized version of that memory store.
125135
136 By default the dream writes its result to a new memory store and doesn't change the input memory store. With `output_behavior` set to `update_existing`, it writes its result into the input memory store instead. The Dreams API is in research preview, so this resource can still change.
137
138 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#how-it-works) for what a dream reads and produces.
139
126140 - `type: "dream"`
127141
128142 - `id: string`
129143
144 The unique ID of the dream (`drm_...`).
145
130146 - `archived_at: string or null`
131147
132148 A timestamp in RFC 3339 format
from line 167
151167
152168 - `type: string`
153169
170 A code for why the dream failed, such as `timeout` or `internal_error`.
171
172 The [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#errors) lists common error codes and when they occur.
173
154174 - `message: string`
155175
176 A human-readable explanation of why the dream failed.
177
156178 - `inputs: array of BetaDreamInput`
157179
180 The sources that the dream reads, from the request that created it.
181
158182 - `BetaDreamMemoryStoreInput object`
159183
160 An input memory store the dream reads from. The dream never mutates this store unless it is also the destination: with output_behavior {type: "update_existing"} the job consolidates this store in place.
184 The memory store that a dream reads, given as an entry in `inputs`.
161185
186 With `output_behavior` set to `update_existing`, the dream writes its result into this memory store. Otherwise the dream doesn't change it.
187
162188 - `type: "memory_store"`
163189
164190 - `memory_store_id: string`
165191
192 The ID of the memory store for the dream to read (`memstore_...`).
193
194 The memory store must be in the same workspace as the dream and must not be archived.
195
166196 minLength: 1
167197
168198 - `BetaDreamSessionsInput object`
169199
170 Input session transcripts the dream reads.
200 The sessions that a dream reads, given as an entry in `inputs`.
171201
172202 - `type: "sessions"`
173203
174204 - `session_ids: array of string`
175205
206 The IDs of the sessions whose transcripts the dream reads (`sesn_...`).
207
208 Give 1 to 100 IDs, with no duplicates. Each session must be in the same workspace as the dream. Responses list the IDs in sorted order.
209
210 The [limits table in the Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#limits) lists all the limits on a dream.
211
176212 - `instructions: string or null`
177213
214 The guidance given when the dream was created, or `null` if none was given.
215
178216 - `model: BetaDreamModelConfig`
179217
180 Model identifier and configuration applied to every pipeline stage. Same wire shape as the Agents API ModelConfig.
218 The model that runs a dream, from the request that created it.
181219
220 The dream uses this model for all of its work. The response always gives the model as an object, even if the request gave only a model ID.
221
182222 - `id: string`
183223
184 Model identifier, e.g. "claude-opus-5". 1-256 characters.
224 The ID of the model that runs the dream, as given in the request that created it.
185225
186226 minLength: 1, maxLength: 256
187227
from line 235
195235
196236 - `output_behavior: BetaOutputBehavior`
197237
238 Which memory store a dream writes its result to. Defaults to `create_new` when left out of a create request.
239
198240 - `BetaOutputBehaviorCreateNew object`
199241
200 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
242 Write the result to a new memory store that starts as a copy of the input memory store. This is the default.
201243
244 The new memory store is in the same workspace as the dream. The dream doesn't change the input memory store.
245
202246 - `type: "create_new"`
203247
204248 - `BetaOutputBehaviorUpdateExisting object`
205249
206 The job writes the consolidated memories into this existing memory store instead of creating one. In EAP the store must be the job's own memory_store input, so the job consolidates the store in place.
250 Write the result into the input memory store instead of a new memory store.
207251
252 The credential must be allowed to write memory stores, or the request returns a 403 error. While another `update_existing` dream on the same memory store hasn't fully stopped, the request returns a 409 error.
253
208254 - `type: "update_existing"`
209255
210256 - `memory_store_id: string`
211257
258 The ID of the memory store for the dream to write its result to (`memstore_...`). It must be the memory store in the `memory_store` entry of `inputs`.
259
212260 minLength: 1
213261
214262 - `outputs: array of BetaDreamOutput`
215263
264 The memory store that holds the dream's result, as a one-item array, or an empty array until the dream records that memory store.
265
266 The array is empty while the dream is `pending` and for a short time after it starts `running`. It can stay empty if the dream fails or is canceled before then. The memory store holds the complete result only once `status` is `completed`.
267
268 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#use-the-output) for how to review and use the result.
269
216270 - `type: "memory_store"`
217271
218272 - `memory_store_id: string`
219273
274 The ID of the memory store that the dream writes its result to (`memstore_...`).
275
276 With `output_behavior` set to `create_new`, this is a new memory store. With `update_existing`, it is the input memory store.
277
220278 - `session_id: string or null`
221279
280 The ID of the session that runs the dream (`sesn_...`), or `null` if that session hasn't started.
281
282 Stream that session's events to follow what the dream reads and writes.
283
284 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#watch-the-pipeline-run) for how to watch a running dream.
285
222286 - `status: BetaDreamStatus`
223287
224 Lifecycle status of a Dream.
288 Where a dream is in its lifecycle.
225289
290 `completed`, `failed`, and `canceled` are final: once a dream has one of these statuses, its status doesn't change again.
291
292 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#lifecycle) for what each status means.
293
226294 - `"pending"`
227295
296 The dream is waiting to start and hasn't read its inputs yet.
297
298 `outputs` is empty and every `usage` count is zero.
299
228300 - `"running"`
229301
302 The dream is reading its inputs and writing its result.
303
304 `usage` updates while the dream has this status.
305
230306 - `"completed"`
231307
308 The dream finished and its output memory store holds the complete result.
309
232310 - `"failed"`
233311
312 The dream stopped with an error, which `error` describes.
313
314 If `outputs` references a memory store, that memory store keeps what the dream wrote before it stopped.
315
234316 - `"canceled"`
235317
318 A cancel request stopped the dream before it reached `completed` or `failed`.
319
320 If `outputs` references a memory store, that memory store keeps what the dream wrote. `usage` can keep changing after the cancel.
321
236322 - `usage: BetaDreamUsage`
237323
238 Cumulative token usage for the dream across every pipeline stage.
324 The tokens that a dream has used so far.
239325
326 The counts are zero while the dream is `pending` and update while it is `running`. They can keep changing after a cancel.
327
328 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#billing) for how dreams are billed. See the [prompt caching guide](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#tracking-cache-performance) for how the input token counts add up.
329
240330 - `cache_creation_input_tokens: number`
241331
242 Total tokens used to create prompt-cache entries (sum of all TTL tiers).
332 The dream's input tokens that were written to the prompt cache, for both the 5-minute and 1-hour cache durations.
243333
244334 format: int32
245335
246336 - `cache_read_input_tokens: number`
247337
248 Total tokens read from prompt cache.
338 The dream's input tokens that were read from the prompt cache.
249339
250340 format: int32
251341
252342 - `input_tokens: number`
253343
254 Total uncached input tokens consumed across every pipeline stage.
344 The dream's input tokens that weren't read from or written to the prompt cache.
255345
256346 format: int32
257347
258348 - `output_tokens: number`
259349
260 Total output tokens generated across every pipeline stage.
350 The tokens that the model generated for the dream.
261351
262352 format: int32
263353