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

# Job event stream (SSE)

> Real-time Server-Sent Events stream of generation progress. Events include pipeline stage transitions, asset completion notifications, and error reports.

The stream closes automatically when the job reaches a terminal state (`succeeded`, `failed`, `cancelled`).

**Event types:** `stage_start`, `stage_complete`, `asset_ready`, `error`, `ping`, `done`

Use the `after` parameter to resume from a specific sequence number (e.g., after a reconnection).



## OpenAPI

````yaml /openapi.json get /v1/jobs/{job_id}/events
openapi: 3.1.0
info:
  title: Gizmo API
  version: 1.0.0
  description: >-
    Programmatic API for AI-powered 3D simulation authoring.


    Generate physics-ready 3D scenes and articulated assets from natural
    language prompts. Export to USD / USDZ (Isaac Sim), MJCF (MuJoCo), and SDF
    (Gazebo). GLB is only available via the editor UI.
servers:
  - url: https://api.gizmo.antimlabs.com
    description: Production
security: []
tags:
  - name: Scenes
    description: >-
      Create, retrieve, update, and delete 3D simulation scenes. Generation is
      async — `POST /v1/scenes` returns a `job_id` for polling.
  - name: Assets
    description: >-
      Manage individual 3D assets (articulated objects, furniture, equipment).
      Each asset belongs to a scene and contains geometry, joints, materials,
      and physics data.
  - name: Jobs
    description: >-
      Monitor and control async generation jobs. Poll with `GET /v1/jobs/{id}`,
      stream real-time progress via `GET /v1/jobs/{id}/events` (SSE), or cancel
      with `POST /v1/jobs/{id}/cancel`.
  - name: Catalog
    description: >-
      Browse the premade asset library — thousands of physics-ready 3D objects
      organized by category. Download GLB/USDZ directly.
  - name: Account
    description: View your identity and API usage statistics.
paths:
  /v1/jobs/{job_id}/events:
    get:
      tags:
        - Jobs
      summary: Job event stream (SSE)
      description: >-
        Real-time Server-Sent Events stream of generation progress. Events
        include pipeline stage transitions, asset completion notifications, and
        error reports.


        The stream closes automatically when the job reaches a terminal state
        (`succeeded`, `failed`, `cancelled`).


        **Event types:** `stage_start`, `stage_complete`, `asset_ready`,
        `error`, `ping`, `done`


        Use the `after` parameter to resume from a specific sequence number
        (e.g., after a reconnection).
      operationId: job_events_v1_jobs__job_id__events_get
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
            title: Job Id
        - name: after
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
            title: After
        - name: authorization
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Authorization
        - name: x-gizmo-service-token
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Gizmo-Service-Token
        - name: x-gizmo-user-id
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Gizmo-User-Id
        - name: x-gizmo-convex-user-id
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Gizmo-Convex-User-Id
      responses:
        '200':
          description: SSE event stream
          content:
            application/json:
              schema: {}
            text/event-stream: {}
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
components:
  schemas:
    ApiErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ApiErrorDetail'
      type: object
      required:
        - error
      title: ApiErrorResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ApiErrorDetail:
      properties:
        code:
          type: string
          title: Code
          description: Machine-readable error code
          examples:
            - scene_not_found
        message:
          type: string
          title: Message
          description: Human-readable description
          examples:
            - Scene sc_abc123 not found
        status:
          type: integer
          title: Status
          description: HTTP status code
          examples:
            - 404
      type: object
      required:
        - code
        - message
        - status
      title: ApiErrorDetail
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````