> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dedaluslabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Watch machine lifecycle status

> Streams machine lifecycle updates over Server-Sent Events. Each `status` event contains a full `LifecycleResponse` payload. The stream closes after the machine reaches its current desired state.



## OpenAPI

````yaml /dcs-openapi.json get /v1/machines/{machine_id}/status/stream
openapi: 3.1.0
info:
  description: Controlplane API for Dedalus Cloud Services (DCS).
  title: Dedalus Cloud Services API
  version: v1
servers:
  - description: Official DCS API
    url: https://dcs.dedaluslabs.ai
security:
  - ApiKeyAuth: []
  - BearerAuth: []
paths:
  /v1/machines/{machine_id}/status/stream:
    get:
      tags:
        - Machine Lifecycle
      summary: Watch machine lifecycle status
      description: >-
        Streams machine lifecycle updates over Server-Sent Events. Each `status`
        event contains a full `LifecycleResponse` payload. The stream closes
        after the machine reaches its current desired state.
      operationId: watchMachineStatus
      parameters:
        - description: Organization ID header applied to all DCS requests.
          in: header
          name: X-Dedalus-Org-Id
          schema:
            format: uuid
            type: string
        - description: Machine identifier.
          in: path
          name: machine_id
          required: true
          schema:
            $ref: '#/components/schemas/MachineIDPathSegment'
        - description: Optional resourceVersion bookmark used to resume a previous stream.
          in: header
          name: Last-Event-ID
          schema:
            type: string
      responses:
        '200':
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/LifecycleResponse'
          description: >-
            Server-Sent Event stream (`text/event-stream`) of machine lifecycle
            updates.
        '401':
          content:
            application/json:
              examples:
                invalid_key:
                  value:
                    error_code: AUTH_INVALID
                    message: invalid Dedalus API key
                    retryable: false
                missing_key:
                  value:
                    error_code: AUTH_REQUIRED
                    message: missing Dedalus API key
                    retryable: false
              schema:
                additionalProperties: false
                properties:
                  details:
                    additionalProperties:
                      type: string
                    type: object
                  error_code:
                    type: string
                  message:
                    type: string
                  retry_after_ms:
                    format: int64
                    type: integer
                  retryable:
                    type: boolean
                required:
                  - error_code
                  - message
                  - retryable
                type: object
          description: Authentication required
        '403':
          content:
            application/json:
              examples:
                org_mismatch:
                  value:
                    error_code: AUTH_ORG_MISMATCH
                    message: org scope does not match API key ownership
                    retryable: false
                scope_forbidden:
                  value:
                    error_code: AUTH_SCOPE_FORBIDDEN
                    message: internal service authorization is required
                    retryable: false
              schema:
                additionalProperties: false
                properties:
                  details:
                    additionalProperties:
                      type: string
                    type: object
                  error_code:
                    type: string
                  message:
                    type: string
                  retry_after_ms:
                    format: int64
                    type: integer
                  retryable:
                    type: boolean
                required:
                  - error_code
                  - message
                  - retryable
                type: object
          description: Forbidden
components:
  schemas:
    MachineIDPathSegment:
      maxLength: 253
      minLength: 4
      pattern: ^dm-[a-z0-9]([a-z0-9-]*[a-z0-9])?$
      type: string
    LifecycleResponse:
      additionalProperties: false
      properties:
        autosleep_seconds:
          description: Seconds of inactivity before autosleep. 0 disables autosleep.
          format: int64
          maximum: 9223372036
          minimum: 0
          type: integer
        desired_state:
          enum:
            - running
            - sleeping
            - destroyed
          type: string
        machine_id:
          type: string
        memory_mib:
          description: Memory in MiB.
          format: int64
          type: integer
        status:
          $ref: '#/components/schemas/LifecycleStatus'
        storage_gib:
          format: int64
          type: integer
        vcpu:
          description: CPU in vCPUs.
          format: double
          type: number
      required:
        - machine_id
        - vcpu
        - memory_mib
        - storage_gib
        - autosleep_seconds
        - desired_state
        - status
      type: object
    LifecycleStatus:
      additionalProperties: false
      properties:
        last_error:
          type: string
        last_progress_at:
          format: date-time
          type: string
        last_transition_at:
          format: date-time
          type: string
        phase:
          enum:
            - accepted
            - placement_pending
            - starting
            - running
            - stopping
            - sleeping
            - destroying
            - destroyed
            - failed
          type: string
        reason:
          type: string
        retryable:
          type: boolean
        revision:
          type: string
      required:
        - phase
        - reason
        - retryable
        - revision
        - last_transition_at
        - last_progress_at
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: Dedalus API key. Alternative to Bearer token.
      in: header
      name: x-api-key
      type: apiKey
    BearerAuth:
      bearerFormat: Dedalus API key
      description: 'Dedalus API key in Authorization: Bearer <key>.'
      scheme: bearer
      type: http

````