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

# Read execution state

> Read canonical status after a timeout or dropped stream. A successful HTTP response does not mean the execution itself succeeded.



## OpenAPI

````yaml /openapi/managed.yaml get /v1/executions/{execution_id}
openapi: 3.1.0
info:
  title: DreamLayer Agent API
  version: '1'
  description: >-
    Generate images, sprite sheets, and quoted videos; follow executions and
    retrieve owned outputs. Start with https://docs.dreamlayer.io/agent-api for
    authentication, limits, runnable examples, event recovery, and billing.
    Sprite sheets require account capability support and an approved credit
    ceiling. Video requires a quote before acceptance. Video schemas document
    the customer integration fields; response objects may contain additional
    fields. See https://docs.dreamlayer.io/agent-api/video.
servers:
  - url: https://api.dreamlayer.io
security:
  - bearerAuth: []
paths:
  /v1/executions/{execution_id}:
    get:
      summary: Read execution state
      description: >-
        Read canonical status after a timeout or dropped stream. A successful
        HTTP response does not mean the execution itself succeeded.
      operationId: getExecution
      parameters:
        - $ref: '#/components/parameters/Version'
        - $ref: '#/components/parameters/ExecutionId'
      responses:
        '200':
          description: Canonical execution state
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ExecutionStatus'
                  - $ref: '#/components/schemas/VideoExecution'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/InvalidRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    Version:
      name: DreamLayer-Version
      in: header
      required: true
      schema:
        type: string
        const: '1'
    ExecutionId:
      name: execution_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
  schemas:
    ExecutionStatus:
      type: object
      additionalProperties: false
      required:
        - execution_id
        - conversation_id
        - status
        - image_job
        - question
        - error
      properties:
        execution_id:
          type: string
          format: uuid
        conversation_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - needs_input
            - queued
            - running
            - completed
            - failed
            - cancelled
        image_job:
          oneOf:
            - $ref: '#/components/schemas/ImageJob'
            - type: 'null'
        question:
          description: >-
            The outstanding clarification, so a client that reconnected or never
            held the stream can still answer it. Null whenever nothing is
            outstanding, which includes an execution whose question has already
            been answered: answering creates a new execution and the one that
            asked stays at status needs_input with a null question. A non-null
            question is the only reliable signal that a turn is still waiting.
            Additive: treat a missing field as null.
          oneOf:
            - $ref: '#/components/schemas/ExecutionQuestion'
            - type: 'null'
        error:
          description: Public admission failure when status is failed; otherwise null.
          oneOf:
            - $ref: '#/components/schemas/ExecutionError'
            - type: 'null'
    VideoExecution:
      type: object
      additionalProperties: false
      required:
        - execution_id
        - conversation_id
        - status
        - image_job
        - video_job
      properties:
        execution_id:
          type: string
          format: uuid
        conversation_id:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/VideoState'
        image_job:
          type: 'null'
        video_job:
          type: object
          additionalProperties: true
          description: >-
            Documented integration fields. Additional response fields can
            include original request data; do not log full responses.
          required:
            - stage
            - requested_settings
            - metadata
            - credits
            - credits_restored
            - settled_credits
            - reserved_credits
            - billing_note
            - error_code
            - retention_expires_at
            - download_url
          properties:
            stage:
              $ref: '#/components/schemas/VideoState'
            requested_settings:
              $ref: '#/components/schemas/VideoSettings'
            metadata:
              type:
                - object
                - 'null'
              description: >-
                Actual delivered metadata, available after validation.
                Dimensions and duration can differ slightly from nominal
                settings.
              properties:
                width:
                  type: integer
                height:
                  type: integer
                duration_seconds:
                  type: number
                fps:
                  type: number
                audio_streams:
                  type: integer
                codec:
                  type: string
                content_type:
                  type: string
                  const: video/mp4
                bytes:
                  type: integer
                  maximum: 268435456
                sha256:
                  type: string
            credits:
              type: string
            credits_restored:
              type: boolean
            settled_credits:
              type: string
            reserved_credits:
              type: string
            billing_note:
              type: string
            error_code:
              type:
                - string
                - 'null'
            retention_expires_at:
              type:
                - string
                - 'null'
              format: date-time
            download_url:
              type:
                - string
                - 'null'
              description: >-
                Owned relative asset path on completion; authenticate only at
                the API origin.
            created_at:
              type:
                - string
                - 'null'
              format: date-time
            completed_at:
              type:
                - string
                - 'null'
              format: date-time
    ImageJob:
      type: object
      additionalProperties: false
      required:
        - public_job_id
        - status
        - finished_assets
        - sanitized_error
      properties:
        public_job_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - queued
            - running
            - completed
            - failed
        finished_assets:
          type: array
          maxItems: 1
          items:
            oneOf:
              - $ref: '#/components/schemas/FinishedAsset'
              - $ref: '#/components/schemas/FinishedBundle'
        sanitized_error:
          oneOf:
            - $ref: '#/components/schemas/SanitizedError'
            - type: 'null'
        frame_review:
          description: >-
            Optional completed-sprite metadata. Null or absent means unknown,
            not a clean inspection result. Older jobs need not contain this
            field. Ordinary images and unfinished jobs return null. All frame
            numbers are one-based output slots, not source-video frame indices.
          oneOf:
            - $ref: '#/components/schemas/SpriteFrameReview'
            - type: 'null'
    ExecutionQuestion:
      type: object
      additionalProperties: false
      required:
        - question_id
        - text
        - requires_asset
      properties:
        question_id:
          type: string
          format: uuid
        text:
          type: string
        requires_asset:
          type: boolean
          description: >-
            When true the answer must carry input_asset_id as well as respond.
            Answering without one is refused with a 422 whose details name
            input_asset_id.
    ExecutionError:
      type: object
      additionalProperties: false
      required:
        - reason
        - message
        - retryable
      properties:
        reason:
          $ref: '#/components/schemas/PublicErrorReason'
        message:
          type: string
        retryable:
          type: boolean
    VideoState:
      type: string
      enum:
        - queued
        - submitting
        - uncertain
        - generating
        - delivering
        - completed
        - failed
        - cancelled
        - expired
    VideoSettings:
      type: object
      additionalProperties: false
      required:
        - duration_seconds
        - resolution
        - aspect_ratio
        - generate_audio
      properties:
        duration_seconds:
          type: integer
        resolution:
          type: string
          const: 720p
        aspect_ratio:
          type: string
          description: >-
            Resolved text aspect or the source-driven profile marker for image
            video. Read delivered metadata for actual width and height.
        generate_audio:
          type: boolean
    ErrorEnvelope:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - reason
            - message
            - category
            - retryable
            - request_id
          properties:
            code:
              type: string
              description: Legacy uppercase code retained for existing clients.
            reason:
              $ref: '#/components/schemas/PublicErrorReason'
            message:
              type: string
            category:
              type: string
            retryable:
              type: boolean
            request_id:
              type: string
              format: uuid
            details:
              type: object
              description: >-
                Optional sanitized validation detail. Submitted values are never
                echoed.
              additionalProperties: true
    FinishedAsset:
      type: object
      additionalProperties: false
      required:
        - asset_id
        - download_url
        - content_type
        - width
        - height
      properties:
        asset_id:
          type: string
          format: uuid
        download_url:
          type: string
        content_type:
          type: string
          const: image/png
        width:
          type: integer
          minimum: 1
          maximum: 4096
        height:
          type: integer
          minimum: 1
          maximum: 4096
    FinishedBundle:
      type: object
      additionalProperties: false
      description: >-
        Complete sprite sheet dimensions, not individual frame dimensions. The
        bounds below cover all supported frame counts and sizes. The correction
        is deployed; frame_size 512 is the default, not a required workaround.
        Existing completed outputs do not require regeneration or another
        charge; retry status and download with the original execution ID.
      required:
        - asset_id
        - download_url
        - content_type
        - width
        - height
        - size_bytes
      properties:
        asset_id:
          type: string
          format: uuid
        download_url:
          type: string
        content_type:
          type: string
          const: application/zip
        width:
          type: integer
          minimum: 32
          maximum: 10800
        height:
          type: integer
          minimum: 32
          maximum: 10800
        size_bytes:
          type: integer
          minimum: 1
          maximum: 134217728
    SanitizedError:
      type: object
      additionalProperties: false
      required:
        - code
        - reason
        - message
        - retryable
        - request_id
      properties:
        code:
          type: string
          const: generation_failed
          description: Legacy value retained for existing clients. New clients use reason.
        reason:
          type: string
          enum:
            - invalid_request
            - rate_limited
            - content_refused
            - temporarily_unavailable
            - generation_failed
            - insufficient_frames
        message:
          type: string
        retryable:
          type: boolean
        request_id:
          type: string
          format: uuid
    SpriteFrameReview:
      type: object
      additionalProperties: false
      required:
        - frame_count
        - background
        - kept_background_frames
        - inspection_frames
        - source_shifted_frames
      description: >-
        Each frame list is ordered, unique, and bounded by frame_count.
        Intentional keep mode lists every slot in kept_background_frames and
        leaves inspection and source-shift lists empty; keeping a requested
        background is not a defect.
      properties:
        frame_count:
          type: integer
          minimum: 7
          maximum: 100
        background:
          type: string
          enum:
            - remove
            - keep
        kept_background_frames:
          type: array
          maxItems: 100
          uniqueItems: true
          description: Output slots delivered with their backgrounds still present.
          items:
            type: integer
            minimum: 1
            maximum: 100
        inspection_frames:
          type: array
          maxItems: 100
          uniqueItems: true
          description: Slots worth inspecting, not a claim that the artwork is defective.
          items:
            type: integer
            minimum: 1
            maximum: 100
        source_shifted_frames:
          type: array
          maxItems: 100
          uniqueItems: true
          description: Slots successfully rescued using a nearby source-video moment.
          items:
            type: integer
            minimum: 1
            maximum: 100
    PublicErrorReason:
      type: string
      enum:
        - invalid_request
        - authentication_failed
        - access_denied
        - resource_not_found
        - insufficient_credits
        - conflict
        - too_many_active_jobs
        - rate_limited
        - quota_exceeded
        - content_refused
        - temporarily_unavailable
        - generation_failed
        - insufficient_frames
        - prompt_policy_blocked
        - feature_unavailable
  responses:
    InvalidRequest:
      description: Invalid request, including a missing required Authorization header
      headers:
        Cache-Control:
          schema:
            type: string
            const: no-store
        Pragma:
          schema:
            type: string
            const: no-cache
        X-Request-ID:
          schema:
            type: string
            format: uuid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Unauthenticated:
      description: >-
        Invalid or revoked API key. A missing Authorization header returns 422
        invalid_request.
      headers:
        Cache-Control:
          schema:
            type: string
            const: no-store
        Pragma:
          schema:
            type: string
            const: no-cache
        X-Request-ID:
          schema:
            type: string
            format: uuid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    NotFound:
      description: Owned resource not found
      headers:
        Cache-Control:
          schema:
            type: string
            const: no-store
        Pragma:
          schema:
            type: string
            const: no-cache
        X-Request-ID:
          schema:
            type: string
            format: uuid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    RateLimited:
      description: >-
        Synchronous request or open-stream limit reached. See
        https://docs.dreamlayer.io/agent-api/limits for scopes and backoff.
        Retry-After and remaining-request headers are not guaranteed.
      headers:
        Cache-Control:
          schema:
            type: string
            const: no-store
        Pragma:
          schema:
            type: string
            const: no-cache
        X-Request-ID:
          schema:
            type: string
            format: uuid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            error:
              code: RATE_LIMITED
              reason: rate_limited
              message: Too many requests. Please try again shortly.
              category: RATE_LIMITED
              retryable: true
              request_id: d34db33f-0000-4000-8000-000000000001
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.