--- title: "Get a Dream" method: GET path: "/v1/dreams/{dream_id}?beta=true" --- # Get a Dream `GET /v1/dreams/{dream_id}?beta=true` ## Request - Base URL: `https://api.anthropic.com` - URL: `https://api.anthropic.com/v1/dreams/{dream_id}?beta=true` - Auth: none declared - TypeScript: (a function with typed inputs; its response is checked against the schema) Get a dream by ID to check its status, output memory store, and token usage. Archived dreams are returned too. See 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. ## Path parameters - `dream_id` string, required ## Headers - `anthropic-version` string: The version of the Claude API you want to use. Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning). - `anthropic-beta` AnthropicBeta[]: This endpoint is in beta: requests must send `dreaming-2026-04-21` in this header. - union: Beta names you can send in the `anthropic-beta` header. See [Beta headers](https://platform.claude.com/docs/en/api/beta-headers) for how to send them and where to find the name a feature needs. - string - 'message-batches-2024-09-24' | 'prompt-caching-2024-07-31' | 'computer-use-2024-10-22' | 'computer-use-2025-01-24' | 'pdfs-2024-09-25' | 'token-counting-2024-11-01' | 'token-efficient-tools-2025-02-19' | 'output-128k-2025-02-19' | 'files-api-2025-04-14' | 'mcp-client-2025-04-04' | 'mcp-client-2025-11-20' | 'dev-full-thinking-2025-05-14' | 'interleaved-thinking-2025-05-14' | 'code-execution-2025-05-22' | 'extended-cache-ttl-2025-04-11' | 'context-1m-2025-08-07' | 'context-management-2025-06-27' | 'model-context-window-exceeded-2025-08-26' | 'skills-2025-10-02' | 'fast-mode-2026-02-01' | 'output-300k-2026-03-24' | 'user-profiles-2026-03-24' | 'user-profiles-2026-08-18' | 'user-profiles-2026-09-04' | 'advisor-tool-2026-03-01' | 'managed-agents-2026-04-01' | 'cache-diagnosis-2026-04-07' | 'dreaming-2026-04-21' | 'thinking-token-count-2026-05-13' | 'server-side-fallback-2026-06-01' | 'server-side-fallback-2026-07-01' | 'fallback-credit-2026-06-01' | 'fallback-credit-2026-07-01' | 'agent-memory-2026-07-22' | 'mid-conversation-tool-changes-2026-07-01' | 'compact-2026-01-12' | 'computer-use-2025-11-24' | 'mcp-tunnels-2026-06-22' | 'structured-outputs-2025-11-13' | 'task-budgets-2026-03-13' | 'thinking-display-updates-2026-08-18' | 'ce-user-management-2026-07-13' | 'mid-conversation-output-config-2026-07-01' | 'thinking-binding-controls-2026-08-01' | 'mid-conversation-system-clear-at-2026-08-21' | 'compact-2026-09-04' | 'inline-tools-2026-09-15' | 'mcp-client-2026-09-15' | 'ce-plugins-2026-09-01' | 'spend-limit-reads-2026-09-26' | 'telemetry-destinations-2026-08-11' | 'webhooks-2026-10-07' | 'admin-user-sign-out-2026-10-08' | 'message-threads-2026-08-12' | 'analytics-usage-cost-2026-08-24' | 'experimental-claude-tag-2026-10-21' - `anthropic-workspace-id` string ## Response `200` Successful response (OK) - BetaDream: An asynchronous job that reads a memory store and past sessions, then writes a reorganized version of that memory store. 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: the request and response shapes are volatile and may change without the deprecation period that applies to stable endpoints. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#how-it-works) for what a dream reads and produces. - `type` 'dream', required - `id` string, required: The unique ID of the dream (`drm_...`). - `inputs` BetaDreamInput[], required: The sources that the dream reads, from the request that created it. - union: A source that a dream reads, such as a memory store or a set of sessions. - object: The memory store that a dream reads, given as an entry in `inputs`. With `output_behavior` set to `update_existing`, the dream writes its result into this memory store. Otherwise the dream doesn't change it. - `type` 'memory_store', required - `memory_store_id` string, required: The ID of the memory store for the dream to read (`memstore_...`). The memory store must be in the same workspace as the dream and must not be archived. - object: The sessions that a dream reads, given as an entry in `inputs`. - `type` 'sessions', required - `session_ids` string[], required: The IDs of the sessions whose transcripts the dream reads (`sesn_...`). 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. - `outputs` BetaDreamOutput[], required: 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#use-the-output) for how to review and use the result. - `type` 'memory_store', required - `memory_store_id` string, required: The ID of the memory store that the dream writes its result to (`memstore_...`). With `output_behavior` set to `create_new`, this is a new memory store. With `update_existing`, it is the input memory store. - `status` 'pending' | 'running' | 'completed' | 'failed' | 'canceled', required: 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#lifecycle) for what each status means. - `created_at` string, date-time, required: A timestamp in RFC 3339 format - `ended_at` string, date-time, required: A timestamp in RFC 3339 format - `archived_at` string, date-time, required: A timestamp in RFC 3339 format - `error` BetaDreamError, required: Failure detail for a Dream whose `status` is `failed`. - `type` string, required: A code for why the dream failed, such as `timeout` or `internal_error`. The [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#errors) lists common error codes and when they occur. - `message` string, required: A human-readable explanation of why the dream failed. - `model` BetaDreamModelConfig, required: 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. - `id` string, required: The ID of the model that runs the dream, as given in the request that created it. - `speed` 'standard' | 'fast' - `instructions` string, nullable, required: The guidance given when the dream was created, or `null` if none was given. - `session_id` string, nullable, required: 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#watch-the-pipeline-run) for how to watch a running dream. - `usage` BetaDreamUsage, required: The tokens that a dream has used so far. The counts are zero while the dream is `pending` and update while it is `running`. They can keep changing after a cancel. 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. - `input_tokens` integer, required: The dream's input tokens that weren't read from or written to the prompt cache. - `output_tokens` integer, required: The tokens that the model generated for the dream. - `cache_read_input_tokens` integer, required: The dream's input tokens that were read from the prompt cache. - `cache_creation_input_tokens` integer, required: The dream's input tokens that were written to the prompt cache, for both the 5-minute and 1-hour cache durations. - `output_behavior` union, required: Which memory store a dream writes its result to. Defaults to `create_new` when left out of a create request. - object: Write the result to a new memory store that starts as a copy of the input memory store. This is the default. The new memory store is in the same workspace as the dream. The dream doesn't change the input memory store. - `type` 'create_new', required - object: Write the result into the input memory store instead of a new memory store. 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. - `type` 'update_existing', required - `memory_store_id` string, required: 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`. ## Other responses - `400`: Invalid argument - The client specified an invalid argument - `401`: Unauthenticated - The request does not have valid authentication credentials - `403`: Permission denied - The caller does not have permission to execute the specified operation - `404`: Not found - Some requested entity was not found - `408`: Deadline exceeded - The deadline expired before the operation could complete - `409`: Custom error status - `412`: Failed precondition - Operation was rejected because the system is not in required state - `413`: Out of range - Operation was attempted past the valid range - `429`: Resource exhausted - Some resource has been exhausted (rate limiting) - `431`: Request header fields too large - Request metadata was too large - `499`: Cancelled - The operation was cancelled by the client - `500`: Internal - Internal server error - `501`: Unimplemented - The operation is not implemented or supported - `503`: Unavailable - The service is currently unavailable - `504`: Deadline exceeded - Upstream service did not respond in time ## Changes - **2026-11-05** `037a593978dc`: 1 info - added the enum value `admin-user-sign-out-2026-10-08` to the property `items/anyOf[subschema #2]/` of the `header` request parameter `anthropic-beta` - **2026-10-23** `f538a797852c`: 1 info - added the enum value `experimental-claude-tag-2026-10-21` to the property `items/anyOf[subschema #2]/` of the `header` request parameter `anthropic-beta` - **2026-10-23** `8071e43a8476`: 1 info - added the enum value `analytics-usage-cost-2026-08-24` to the property `items/anyOf[subschema #2]/` of the `header` request parameter `anthropic-beta` - **2026-10-22** `376dea998624`: 1 info - added the enum value `message-threads-2026-08-12` to the property `items/anyOf[subschema #2]/` of the `header` request parameter `anthropic-beta` - **2026-10-21** `94c83daca660`: 1 warning, 12 info - deleted the `header` request parameter `x-api-key` - the `type` response property const value `create_new` was added for the status `200` - the `type` response property const value `dream` was added for the status `200` - the `type` response property const value `memory_store` was added for the status `200` - …9 more [Operation history](https://skmtc.dev/anthropics/apis/anthropic-api/changes/v1/dreams/:dream_id%3Fbeta=true/get.md) --- [API](https://skmtc.dev/anthropics/apis/anthropic-api.md) - [All operations](https://skmtc.dev/anthropics/apis/anthropic-api/llms.txt) - [OpenAPI document](https://skmtc.dev/anthropics/apis/anthropic-api/revisions/690622377a5e?raw)