> ## 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.

# List Run Bugs

> Retrieve all bugs detected during a specific run.

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

Retrieve all bugs detected during a specific run.

## Path Parameters

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

## Response

<ResponseField name="data" type="BugOccurrence[]" required>
  Array of bug occurrences found during the run
</ResponseField>

<ResponseField name="pagination" type="object" required>
  Pagination metadata (`page`, `page_size`, `total_count`, `total_pages`).
  Bug occurrences per run are naturally bounded, so the response always
  returns the full list in a single page — the envelope is kept to match the
  shape of other list routes.
</ResponseField>

### Bug Occurrence Object

<ResponseField name="id" type="string" required>
  Unique occurrence ID
</ResponseField>

<ResponseField name="bug_id" type="string" required>
  Bug identifier (same bug across runs shares this ID)
</ResponseField>

<ResponseField name="title" type="string" required>
  Short bug title
</ResponseField>

<ResponseField name="description" type="string" required>
  Detailed description of the bug
</ResponseField>

<ResponseField name="category" type="string" required>
  Bug category: `ui`, `gameplay`, `performance`, `crash`, `audio`, `visual`
</ResponseField>

<ResponseField name="severity" type="string" required>
  Severity level: `low`, `medium`, `high`, `critical`
</ResponseField>

<ResponseField name="confidence" type="string" required>
  Detection confidence: `low`, `medium`, `high`
</ResponseField>

<ResponseField name="reproduction_steps" type="string" required>
  Steps to reproduce the bug
</ResponseField>

<ResponseField name="player_number" type="integer" required>
  Which player encountered the bug (0-indexed)
</ResponseField>

<ResponseField name="test_step" type="integer" required>
  Test step where bug was detected
</ResponseField>

<ResponseField name="turn" type="integer" required>
  Agent turn number when detected
</ResponseField>

<ResponseField name="detected_at" type="string" required>
  ISO 8601 timestamp when bug was detected
</ResponseField>

<ResponseField name="details" type="object">
  Additional bug-specific details (screenshots, element IDs, etc.)
</ResponseField>

## Severity Levels

<AccordionGroup>
  <Accordion title="Critical" icon="circle-exclamation">
    Blocks core functionality or causes crashes. Requires immediate attention.
  </Accordion>

  <Accordion title="High" icon="triangle-exclamation">
    Major feature broken or significantly impaired. Should be fixed before release.
  </Accordion>

  <Accordion title="Medium" icon="circle-info">
    Feature works but with noticeable issues. Should be addressed in normal development cycle.
  </Accordion>

  <Accordion title="Low" icon="circle-check">
    Minor issues with minimal impact. Can be fixed when convenient.
  </Accordion>
</AccordionGroup>

<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/bugs" \
    -H "X-Api-Key: YOUR_API_TOKEN"
  ```

  ```typescript JavaScript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  const runId = "lkkg6t5612m";

  const response = await fetch(`https://nunu.ai/api/v1/project/your-project-id/runs/${runId}/bugs`, {
    headers: {
      "X-Api-Key": process.env.NUNU_API_TOKEN,
    },
  });
  const data = await response.json();
  ```

  ```python Python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  import requests
  import os

  run_id = "lkkg6t5612m"

  response = requests.get(
      f"https://nunu.ai/api/v1/project/your-project-id/runs/{run_id}/bugs",
      headers={"X-Api-Key": os.environ["NUNU_API_TOKEN"]}
  )
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  {
    "data": [
      {
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "bug_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "title": "Button not responding",
        "description": "The 'Start Game' button does not respond to taps after returning from settings menu.",
        "category": "ui",
        "severity": "high",
        "confidence": "high",
        "reproduction_steps": "1. Open app\n2. Go to settings\n3. Return to main menu\n4. Try to tap Start Game button",
        "player_number": 0,
        "test_step": 2,
        "turn": 15,
        "detected_at": "2025-01-12T10:08:30Z",
        "details": {
          "screenshot_url": "https://bouncer.nunu.ai/artifacts/...",
          "element_id": "btn_start_game"
        }
      }
    ],
    "pagination": {
      "page": 0,
      "page_size": 1,
      "total_count": 1,
      "total_pages": 1
    }
  }
  ```
</ResponseExample>

***

## Aggregate Bugs Across Runs

Here's an example of fetching bugs from multiple recent runs:

<CodeGroup>
  ```python Python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  import requests
  import os

  API_TOKEN = os.environ["NUNU_API_TOKEN"]
  PROJECT_ID = os.environ["NUNU_PROJECT_ID"]
  BASE_URL = f"https://nunu.ai/api/v1/project/{PROJECT_ID}"
  headers = {"X-Api-Key": API_TOKEN}

  def get_recent_bugs(limit=10):
      """Fetch bugs from the most recent completed runs."""
      all_bugs = []
      
      # Get recent completed runs
      response = requests.get(
          f"{BASE_URL}/runs",
          headers=headers,
          params={"state": "completed", "page_size": limit}
      )
      runs = response.json()["data"]
      
      # Fetch bugs for each run
      for run in runs:
          run_id = run["multiplayer_run_id"]
          bugs_response = requests.get(
              f"{BASE_URL}/runs/{run_id}/bugs",
              headers=headers
          )
          bugs_data = bugs_response.json()
          
          for bug in bugs_data["data"]:
              all_bugs.append({
                  "run_id": run_id,
                  "test_name": run["test"]["name"],
                  **bug
              })
      
      return all_bugs

  bugs = get_recent_bugs()
  for bug in bugs:
      print(f"[{bug['severity'].upper()}] {bug['title']} - {bug['test_name']}")
  ```

  ```typescript JavaScript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  const API_TOKEN = process.env.NUNU_API_TOKEN;
  const PROJECT_ID = process.env.NUNU_PROJECT_ID;
  const BASE_URL = `https://nunu.ai/api/v1/project/${PROJECT_ID}`;

  async function getRecentBugs(limit = 10) {
    const headers = { "X-Api-Key": API_TOKEN };
    
    const runsResponse = await fetch(
      `${BASE_URL}/runs?state=completed&page_size=${limit}`,
      { headers }
    );
    const { data: runs } = await runsResponse.json();
    
    const allBugs = [];
    
    for (const run of runs) {
      const bugsResponse = await fetch(
        `${BASE_URL}/runs/${run.multiplayer_run_id}/bugs`,
        { headers }
      );
      const { data: bugOccurrences } = await bugsResponse.json();
      
      for (const bug of bugOccurrences) {
        allBugs.push({
          run_id: run.multiplayer_run_id,
          test_name: run.test.name,
          ...bug
        });
      }
    }
    
    return allBugs;
  }
  ```
</CodeGroup>


## OpenAPI

````yaml GET /project/{projectId}/runs/{runId}/bugs
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}/bugs:
    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: List Run Bugs
      description: Retrieve all bugs detected during a specific run.
      operationId: listRunBugs
      parameters:
        - name: runId
          in: path
          required: true
          description: The multiplayer run ID
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBugsResponse'
        '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:
    ListBugsResponse:
      type: object
      description: >-
        Bugs detected during a multiplayer run. Bug occurrences per run are
        naturally bounded, so the response always returns the full list in a
        single page; the pagination envelope is kept to match the shape of other
        list routes.
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BugOccurrence'
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
        - data
        - pagination
    Error:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
        details:
          type: object
    BugOccurrence:
      type: object
      properties:
        id:
          type: string
          description: Unique occurrence ID
        bug_id:
          type: string
          description: Bug identifier (same bug across runs shares this ID)
        title:
          type: string
          description: Short bug title
        description:
          type: string
          description: Detailed description
        category:
          type: string
          description: Bug category (e.g., ui, gameplay, performance)
        severity:
          type: string
          enum:
            - low
            - medium
            - high
            - critical
          description: Severity level
        confidence:
          type: string
          enum:
            - low
            - medium
            - high
          description: Detection confidence
        reproduction_steps:
          type: string
          description: Steps to reproduce
        player_number:
          type: integer
          description: Which player encountered the bug (0-indexed)
        test_step:
          type: integer
          description: Test step where bug was detected
        turn:
          type: integer
          description: Agent turn number when detected
        detected_at:
          type: string
          format: date-time
        details:
          type: object
          description: Additional bug-specific details
    Pagination:
      type: object
      properties:
        page:
          type: integer
        page_size:
          type: integer
        total_count:
          type: integer
        total_pages:
          type: integer
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: API key for authentication

````