--- title: List Dreams url: https://platform.claude.com/docs/en/api/php/beta/dreams/list --- # List Dreams `$client->beta->dreams->list(?\Datetime createdAtGt, ?\Datetime createdAtLt, ?bool includeArchived, ?int limit, ?string page, ?list statuses, ?list betas, ?string workspaceID): PageCursor` **GET** `/v1/dreams` List the dreams in the workspace, newest first. Archived dreams are left out unless `include_archived` is `true`. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=php#list-dreams) for how to page through dreams. ## Parameters - `createdAtGt?: optional \Datetime` (query parameter) Return only dreams created after this time (exclusive), in RFC 3339. - `createdAtLt?: optional \Datetime` (query parameter) Return only dreams created before this time (exclusive), in RFC 3339. - `includeArchived?: optional bool` (query parameter) Whether to include archived dreams. Defaults to `false`. - `limit?: optional int` (query parameter) The maximum number of dreams to return, from 1 to 100. Defaults to 20. - `page?: optional string` (query parameter) The cursor for the page to return, taken from `next_page` in a previous response. Leave it out to get the first page. - `statuses?: optional list` (query parameter) Return only dreams that have one of these statuses. Repeat the parameter to give more than one status. Leave it out to return dreams of every status. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `dreaming-2026-04-21` in this header. - `workspaceID?: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). 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. ## Returns - `class BetaDream` - `"dream" type` - `string id` The unique ID of the dream (`drm_...`). - `?\Datetime archivedAt` When the dream was archived, in RFC 3339, or `null` if it hasn't been archived. - `\Datetime createdAt` When the dream was created, in RFC 3339. Lists of dreams are sorted by this time, newest first. - `?\Datetime endedAt` When the dream reached `completed`, `failed`, or `canceled`, in RFC 3339, or `null` if it is still `pending` or `running`. - `?BetaDreamError error` Why the dream failed, or `null` if `status` isn't `failed`. - `list inputs` The sources that the dream reads, from the request that created it. - `?string instructions` The guidance given when the dream was created, or `null` if none was given. - `BetaDreamModelConfig model` The model that runs a dream, from the request that created it. 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. - `BetaOutputBehavior outputBehavior` Where the dream writes its result, as set in the request that created the dream. If that request left out `output_behavior`, the dream used the `create_new` behavior. - `list outputs` 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. 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`. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=php#use-the-output) for how to review and use the result. - `?string sessionID` The ID of the session that runs the dream (`sesn_...`), or `null` if that session hasn't started. Stream that session's events to follow what the dream reads and writes. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=php#watch-the-pipeline-run) for how to watch a running dream. - `BetaDreamStatus status` Where a dream is in its lifecycle. `completed`, `failed`, and `canceled` are final: once a dream has one of these statuses, its status doesn't change again. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=php#lifecycle) for what each status means. - `BetaDreamUsage usage` The dream's token counts, which stop changing once its `status` is `completed` or `failed`. After a cancel, they can keep changing. ## Example ```php beta->dreams->list( createdAtGt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), createdAtLt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), includeArchived: true, limit: 0, page: 'page', statuses: [BetaDreamStatus::PENDING], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($page); ``` ### Response (200) ```json { "data": [ { "id": "id", "archived_at": "2019-12-27T18:11:19.117Z", "created_at": "2019-12-27T18:11:19.117Z", "ended_at": "2019-12-27T18:11:19.117Z", "error": { "message": "message", "type": "type" }, "inputs": [ { "memory_store_id": "x", "type": "memory_store" } ], "instructions": "instructions", "model": { "id": "x", "speed": "standard" }, "output_behavior": { "type": "create_new" }, "outputs": [ { "memory_store_id": "memory_store_id", "type": "memory_store" } ], "session_id": "session_id", "status": "pending", "type": "dream", "usage": { "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "input_tokens": 0, "output_tokens": 0 } } ], "next_page": "next_page" } ```