Skip to main content
Dreams

Get a Dream

Retrieve a Dream's status, results, and usage by ID.

GET /api/v1/forward/dreams/{id} After creating a Dream, poll this endpoint until status reaches a terminal state: completed, failed, or canceled.

Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT or admin SAT>.

Path parameters

ParameterTypeRequiredDescription
idstringYesDream ID with the drm_ prefix.

Example request

curl -s 'https://api.qoder.com/api/v1/forward/dreams/drm_019e86b4a8f070a3b6c5d4e3f2a1b0c9' \
  -H "Authorization: Bearer $QODER_PAT"

Example response

HTTP 200 OK
{
  "id": "drm_019e86b4a8f070a3b6c5d4e3f2a1b0c9",
  "type": "dream",
  "status": "completed",
  "inputs": [{
    "type": "identity_template",
    "identity_id": "idn_019eabc123",
    "template_id": "tmpl_support"
  }],
  "outputs": [{
    "type": "memory_store",
    "memory_store_id": "memstore_019e86b4b10578059435632bb357c5ed",
    "files_touched": ["preferences.md", "project/architecture.md"]
  }],
  "model": { "id": "auto" },
  "instructions": "Focus on long-term preferences confirmed by the user",
  "usage": {
    "input_tokens": 12500,
    "output_tokens": 3200,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 8000
  },
  "error": null,
  "created_at": "2026-09-15T03:00:00Z",
  "ended_at": "2026-09-15T03:03:42Z",
  "archived_at": null
}

Response fields

FieldTypeDescription
Return valueobjectThe Dream object in its current state.

Errors

HTTPTypeTrigger
400invalid_request_errorid is not a valid Dream ID. error.code is invalid_dream_id.
401authentication_errorAuthentication is missing, invalid, or expired.
403permission_errorThe token cannot query Dreams. Identity SAT is not supported by this endpoint.
404not_found_errorThe Dream does not exist or is not visible to the caller. error.code is dream_not_found.
500/502/503api_errorThe service or an internal dependency is temporarily unavailable.
Best Practices
API reference