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

# Get Live Run Snapshot

> Return a live snapshot for an active run, including latest game state and (optionally) per-player screenshots.

<Info>
  **Permission Required**: `project:read-runs`
</Info>

Return a live snapshot of an active run: latest game state and (optionally) a
screenshot per player, pulled from the newest beholder step. Useful for
displaying real-time progress in a custom dashboard or for quick programmatic
checks while a run is executing.

For completed-run details, use [Get Run](/api-reference/runs/get-run).

## Path Parameters

<ParamField path="runId" type="string" required>
  The multiplayer run ID (12 lowercase alphanumeric characters)
</ParamField>

## Query Parameters

<ParamField query="include_screenshot" type="boolean" default="true">
  Whether to include a base64-encoded screenshot per player. Set to `false`
  for a lighter-weight response.
</ParamField>

## Response

<ResponseField name="multiplayer_run_id" type="string" required>
  Run ID (echoes the path param)
</ResponseField>

<ResponseField name="state" type="string" required>
  Run state: `initializing`, `running`, or `completed`
</ResponseField>

<ResponseField name="test" type="object" required>
  The test that the run is executing

  <Expandable title="test properties">
    <ResponseField name="test.id" type="string">
      Test ID
    </ResponseField>

    <ResponseField name="test.name" type="string">
      Test name
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="players" type="LivePlayer[]" required>
  Snapshot per player

  <Expandable title="LivePlayer properties">
    <ResponseField name="player_number" type="integer">
      Player number (0-indexed)
    </ResponseField>

    <ResponseField name="composite_run_id" type="string">
      Composite run ID for this player
    </ResponseField>

    <ResponseField name="current_run_id" type="string">
      Currently executing inner run ID, or `null`
    </ResponseField>

    <ResponseField name="current_step" type="integer">
      Latest beholder step number, or `null`
    </ResponseField>

    <ResponseField name="game_state" type="object">
      Latest captured game state, or `null`
    </ResponseField>

    <ResponseField name="screenshot" type="object">
      Latest screenshot — `{ data, mimeType, encoding: "base64" }` — or `null`
      if not available or `include_screenshot=false`
    </ResponseField>

    <ResponseField name="last_agent_step" type="object">
      Latest agent reasoning entry — `{ agent, step, save_data, start_time }` —
      or `null`
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  curl -X GET "https://nunu.ai/api/v1/project/your-project-id/runs/lkkg6t5612m/live?include_screenshot=true" \
    -H "X-Api-Key: YOUR_API_TOKEN"
  ```

  ```bash cURL (lightweight) theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  curl -X GET "https://nunu.ai/api/v1/project/your-project-id/runs/lkkg6t5612m/live?include_screenshot=false" \
    -H "X-Api-Key: YOUR_API_TOKEN"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  {
    "multiplayer_run_id": "lkkg6t5612m",
    "state": "RUNNING",
    "test": {
      "id": "a5060a07-d386-4269-98ce-b33fb894201e",
      "name": "Sanity smoke"
    },
    "players": [
      {
        "player_number": 0,
        "composite_run_id": "lkkg6t5612m-1",
        "current_run_id": "run_abc123",
        "current_step": 4,
        "game_state": { "scene": "main_menu" },
        "screenshot": {
          "data": "iVBORw0KGgoAAAANSUhEUgAA...",
          "mimeType": "image/png",
          "encoding": "base64"
        },
        "last_agent_step": {
          "agent": "user-beholder",
          "step": 12,
          "save_data": { "reasoning": "navigated to main menu" },
          "start_time": "2026-04-01T09:55:01.000000+00:00"
        }
      }
    ]
  }
  ```
</ResponseExample>


## OpenAPI

````yaml GET /project/{projectId}/runs/{runId}/live
openapi: 3.1.0
info:
  title: nunu.ai API
  description: >-
    The nunu.ai Public API allows you to programmatically interact with your
    projects, manage test runs, and upload builds.
  version: 1.0.0
servers:
  - url: https://nunu.ai/api/v1
security:
  - apiKeyAuth: []
paths:
  /project/{projectId}/runs/{runId}/live:
    parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
        description: >-
          The project ID. You can copy it from the project settings page or the
          project URL in the dashboard.
    get:
      tags:
        - Runs
      summary: Get Live Run Snapshot
      description: >-
        Return a live snapshot for an active run, including latest game state
        and (optionally) per-player screenshots.
      operationId: getLiveRunSnapshot
      parameters:
        - name: runId
          in: path
          required: true
          description: The multiplayer run ID (12 lowercase alphanumeric characters)
          schema:
            type: string
            pattern: ^[a-z0-9]{12}$
        - name: include_screenshot
          in: query
          description: Whether to include per-player screenshots
          schema:
            type: boolean
            default: true
      responses:
        '200':
          description: Live run snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LiveRunSnapshot'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Run not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    LiveRunSnapshot:
      type: object
      properties:
        multiplayer_run_id:
          type: string
        state:
          type: string
          enum:
            - initializing
            - running
            - completed
        test:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
        players:
          type: array
          items:
            $ref: '#/components/schemas/LiveRunPlayer'
    Error:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
        details:
          type: object
    LiveRunPlayer:
      type: object
      properties:
        player_number:
          type: integer
        composite_run_id:
          type: string
        current_run_id:
          type: string
          nullable: true
        current_step:
          type: integer
          nullable: true
        game_state:
          type: object
          nullable: true
        screenshot:
          type: object
          nullable: true
          properties:
            data:
              type: string
              description: base64-encoded image bytes
            mimeType:
              type: string
            encoding:
              type: string
              enum:
                - base64
        last_agent_step:
          type: object
          nullable: true
          properties:
            agent:
              type: string
            step:
              type: integer
            save_data:
              type: object
            start_time:
              type: string
              format: date-time
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: API key for authentication

````