The whole hunk
from line 7, old and new numbered
/
lines
from line 7
77
88**GET** `/v1/dreams`
99
10List Dreams
10List the dreams in the workspace, newest first.
1111
12Archived dreams are left out unless `include_archived` is `true`.
13
14See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#list-dreams) for how to page through dreams.
15
1216## Query parameters
1317
1418- `"created_at[gt]": optional string`
1519
16 Return dreams with `created_at` strictly after this timestamp (exclusive lower bound, RFC 3339). Unset applies no lower bound.
20 Return only dreams created after this time (exclusive), in RFC 3339.
1721
1822 format: date-time
1923
2024- `"created_at[lt]": optional string`
2125
22 Return dreams with `created_at` strictly before this timestamp (exclusive upper bound, RFC 3339). Unset applies no upper bound.
26 Return only dreams created before this time (exclusive), in RFC 3339.
2327
2428 format: date-time
2529
2630- `include_archived: optional boolean`
2731
28 Query parameter for include_archived
32 Whether to include archived dreams. Defaults to `false`.
2933
3034- `limit: optional number`
3135
32 Query parameter for limit
36 The maximum number of dreams to return, from 1 to 100. Defaults to 20.
3337
3438 format: int32
3539
3640- `page: optional string`
3741
38 Query parameter for page
42 The cursor for the page to return, taken from `next_page` in a previous response.
3943
44 Leave it out to get the first page.
45
4046- `statuses: optional array of BetaDreamStatus`
4147
42 Filter by lifecycle status. Repeat the parameter to match any of multiple statuses. Empty applies no status filter.
48 Return only dreams that have one of these statuses.
4349
50 Repeat the parameter to give more than one status. Leave it out to return dreams of every status.
51
4452 - `"pending"`
4553
54 The dream is waiting to start and hasn't read its inputs yet.
55
56 `outputs` is empty and every `usage` count is zero.
57
4658 - `"running"`
4759
60 The dream is reading its inputs and writing its result.
61
62 `usage` updates while the dream has this status.
63
4864 - `"completed"`
4965
66 The dream finished and its output memory store holds the complete result.
67
5068 - `"failed"`
5169
70 The dream stopped with an error, which `error` describes.
71
72 If `outputs` references a memory store, that memory store keeps what the dream wrote before it stopped.
73
5274 - `"canceled"`
5375
76 A cancel request stopped the dream before it reached `completed` or `failed`.
77
78 If `outputs` references a memory store, that memory store keeps what the dream wrote. `usage` can keep changing after the cancel.
79
5480## Headers
5581
5682- `"anthropic-beta": optional array of AnthropicBeta`
from line 181
155181
156182- `"anthropic-workspace-id": optional string`
157183
184 Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`).
185
186 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.
187
158188## Returns
159189
160190- `data: array of BetaDream`
161191
192 The dreams on this page, newest first.
193
162194 - `type: "dream"`
163195
164196 - `id: string`
165197
198 The unique ID of the dream (`drm_...`).
199
166200 - `archived_at: string or null`
167201
168202 A timestamp in RFC 3339 format
from line 221
187221
188222 - `type: string`
189223
224 A code for why the dream failed, such as `timeout` or `internal_error`.
225
226 The [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#errors) lists common error codes and when they occur.
227
190228 - `message: string`
191229
230 A human-readable explanation of why the dream failed.
231
192232 - `inputs: array of BetaDreamInput`
193233
234 The sources that the dream reads, from the request that created it.
235
194236 - `BetaDreamMemoryStoreInput object`
195237
196 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.
238 The memory store that a dream reads, given as an entry in `inputs`.
197239
240 With `output_behavior` set to `update_existing`, the dream writes its result into this memory store. Otherwise the dream doesn't change it.
241
198242 - `type: "memory_store"`
199243
200244 - `memory_store_id: string`
201245
246 The ID of the memory store for the dream to read (`memstore_...`).
247
248 The memory store must be in the same workspace as the dream and must not be archived.
249
202250 minLength: 1
203251
204252 - `BetaDreamSessionsInput object`
205253
206 Input session transcripts the dream reads.
254 The sessions that a dream reads, given as an entry in `inputs`.
207255
208256 - `type: "sessions"`
209257
210258 - `session_ids: array of string`
211259
260 The IDs of the sessions whose transcripts the dream reads (`sesn_...`).
261
262 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.
263
264 The [limits table in the Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#limits) lists all the limits on a dream.
265
212266 - `instructions: string or null`
213267
268 The guidance given when the dream was created, or `null` if none was given.
269
214270 - `model: BetaDreamModelConfig`
215271
216 Model identifier and configuration applied to every pipeline stage. Same wire shape as the Agents API ModelConfig.
272 The model that runs a dream, from the request that created it.
217273
274 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.
275
218276 - `id: string`
219277
220 Model identifier, e.g. "claude-opus-5". 1-256 characters.
278 The ID of the model that runs the dream, as given in the request that created it.
221279
222280 minLength: 1, maxLength: 256
223281
from line 289
231289
232290 - `output_behavior: BetaOutputBehavior`
233291
292 Which memory store a dream writes its result to. Defaults to `create_new` when left out of a create request.
293
234294 - `BetaOutputBehaviorCreateNew object`
235295
236 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.
296 Write the result to a new memory store that starts as a copy of the input memory store. This is the default.
237297
298 The new memory store is in the same workspace as the dream. The dream doesn't change the input memory store.
299
238300 - `type: "create_new"`
239301
240302 - `BetaOutputBehaviorUpdateExisting object`
241303
242 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.
304 Write the result into the input memory store instead of a new memory store.
243305
306 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.
307
244308 - `type: "update_existing"`
245309
246310 - `memory_store_id: string`
247311
312 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`.
313
248314 minLength: 1
249315
250316 - `outputs: array of BetaDreamOutput`
251317
318 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.
319
320 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`.
321
322 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#use-the-output) for how to review and use the result.
323
252324 - `type: "memory_store"`
253325
254326 - `memory_store_id: string`
255327
328 The ID of the memory store that the dream writes its result to (`memstore_...`).
329
330 With `output_behavior` set to `create_new`, this is a new memory store. With `update_existing`, it is the input memory store.
331
256332 - `session_id: string or null`
257333
334 The ID of the session that runs the dream (`sesn_...`), or `null` if that session hasn't started.
335
336 Stream that session's events to follow what the dream reads and writes.
337
338 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#watch-the-pipeline-run) for how to watch a running dream.
339
258340 - `status: BetaDreamStatus`
259341
260 Lifecycle status of a Dream.
342 Where a dream is in its lifecycle.
261343
344 `completed`, `failed`, and `canceled` are final: once a dream has one of these statuses, its status doesn't change again.
345
346 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#lifecycle) for what each status means.
347
262348 - `"pending"`
263349
350 The dream is waiting to start and hasn't read its inputs yet.
351
352 `outputs` is empty and every `usage` count is zero.
353
264354 - `"running"`
265355
356 The dream is reading its inputs and writing its result.
357
358 `usage` updates while the dream has this status.
359
266360 - `"completed"`
267361
362 The dream finished and its output memory store holds the complete result.
363
268364 - `"failed"`
269365
366 The dream stopped with an error, which `error` describes.
367
368 If `outputs` references a memory store, that memory store keeps what the dream wrote before it stopped.
369
270370 - `"canceled"`
271371
372 A cancel request stopped the dream before it reached `completed` or `failed`.
373
374 If `outputs` references a memory store, that memory store keeps what the dream wrote. `usage` can keep changing after the cancel.
375
272376 - `usage: BetaDreamUsage`
273377
274 Cumulative token usage for the dream across every pipeline stage.
378 The tokens that a dream has used so far.
275379
380 The counts are zero while the dream is `pending` and update while it is `running`. They can keep changing after a cancel.
381
382 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.
383
276384 - `cache_creation_input_tokens: number`
277385
278 Total tokens used to create prompt-cache entries (sum of all TTL tiers).
386 The dream's input tokens that were written to the prompt cache, for both the 5-minute and 1-hour cache durations.
279387
280388 format: int32
281389
282390 - `cache_read_input_tokens: number`
283391
284 Total tokens read from prompt cache.
392 The dream's input tokens that were read from the prompt cache.
285393
286394 format: int32
287395
288396 - `input_tokens: number`
289397
290 Total uncached input tokens consumed across every pipeline stage.
398 The dream's input tokens that weren't read from or written to the prompt cache.
291399
292400 format: int32
293401
294402 - `output_tokens: number`
295403
296 Total output tokens generated across every pipeline stage.
404 The tokens that the model generated for the dream.
297405
298406 format: int32
299407
300408- `next_page: string or null`
409
410 The cursor for the next page, or `null` if this is the last page.
411
412 Pass it as `page` to get the next page.
301413
302414## Example
303415