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

> Retrieve a single test case, optionally by version.

<Info>
  **Authentication**: Any authenticated API key
</Info>

Retrieve the full body of a single test case, including its players, steps,
and any referenced shared step collections.

## Path Parameters

<ParamField path="testId" type="string" required>
  The test ID (UUID)
</ParamField>

## Query Parameters

<ParamField query="version" type="integer">
  Fetch a specific version of the test instead of the latest. Must be a
  positive integer.
</ParamField>

<ParamField query="include_shared_collection_steps" type="boolean" default="true">
  Whether shared step collections should be expanded inline. When `false`,
  shared collection items are returned without their `steps_by_key` /
  `step_order` (the caller can resolve them via [Get Shared Step](/api-reference/shared-steps/get-shared-step)).
</ParamField>

## Response

The body is a `TestCase` object whose shape depends on `test_type`. All variants share the
following base fields, and each variant adds its own `players_by_key` shape.

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

<ResponseField name="project_id" type="string" required>
  Project the test belongs to
</ResponseField>

<ResponseField name="name" type="string" required>
  Test name
</ResponseField>

<ResponseField name="version" type="integer" required>
  Current version. Pass this back in the `expected_version` field when calling
  [Update Test](/api-reference/tests/update-test).
</ResponseField>

<ResponseField name="test_type" type="string" required>
  One of: `verification`, `discovery`, `task`
</ResponseField>

<ResponseField name="tags" type="string[]" required>
  Test tags
</ResponseField>

<ResponseField name="quarantined" type="boolean" required>
  Whether the test is quarantined
</ResponseField>

<ResponseField name="incident_auto_approve" type="boolean" required>
  Whether incidents on this test are auto-approved
</ResponseField>

<ResponseField name="source" type="string" required>
  How the test was authored: `repository` or `bot`
</ResponseField>

<ResponseField name="players_by_key" type="object" required>
  Map of player key → player definition. The shape inside each player depends
  on `test_type`. For `verification` tests, players carry an `items_by_key` /
  `item_order` describing each step or shared collection reference.
</ResponseField>

<ResponseField name="player_order" type="string[]" required>
  Ordered list of player keys
</ResponseField>

<ResponseField name="testrail" type="object">
  TestRail integration metadata, or `null`
</ResponseField>

<ResponseField name="min_seconds" type="integer">
  Test-level minimum runtime in seconds. Returned for `discovery` and `task`
  tests. `verification` tests have no minimum.
</ResponseField>

<ResponseField name="max_seconds" type="integer">
  Test-level maximum runtime in seconds. Returned for all test types.
</ResponseField>

## Verification step shape

Each `step` item inside a verification player's `items_by_key` has the
following fields:

<ResponseField name="goal" type="string" required>
  The instructions for the step — what the agent should do.
</ResponseField>

<ResponseField name="expected_results" type="object[]" required>
  The list of independent checks the agent verifies for this step. Each entry
  is an object with an `expected` string (one observable outcome). A step can
  carry several atomic checks — one entry per check.
</ResponseField>

<ResponseField name="finish_condition" type="string" required>
  Legacy single-string rendering of the expected results, kept for backwards
  compatibility. On read it is always populated: a single result is returned
  verbatim, multiple results are joined as a numbered list
  (`"1. …\n2. …"`). Prefer `expected_results`; treat `finish_condition` as
  derived/read-only.
</ResponseField>

<ResponseField name="screenshots" type="integer" required>
  How many screenshots the agent captures per turn for this step.
</ResponseField>

<ResponseField name="pause_game" type="boolean" required>
  Whether the game is paused while the agent reasons about this step.
</ResponseField>

<ResponseField name="performance_monitoring" type="boolean" required>
  Whether performance monitoring is enabled for this step.
</ResponseField>

<ResponseField name="hint_manual" type="string[]" required>
  Optional hints that guide the agent through tricky situations.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  curl -X GET "https://nunu.ai/api/v1/project/your-project-id/tests/a5060a07-d386-4269-98ce-b33fb894201e" \
    -H "X-Api-Key: YOUR_API_TOKEN"
  ```

  ```bash cURL (specific version) theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  curl -X GET "https://nunu.ai/api/v1/project/your-project-id/tests/a5060a07-d386-4269-98ce-b33fb894201e?version=3" \
    -H "X-Api-Key: YOUR_API_TOKEN"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  {
    "id": "a5060a07-d386-4269-98ce-b33fb894201e",
    "project_id": "test",
    "name": "Sanity smoke",
    "version": 4,
    "tags": ["smoke"],
    "incident_auto_approve": false,
    "test_type": "verification",
    "quarantined": false,
    "testrail": null,
    "source": "repository",
    "max_seconds": 19800,
    "players_by_key": {
      "1": {
        "name": "P1",
        "agent_config_id": null,
        "game_funcs_config_id": null,
        "items_by_key": {
          "1": {
            "type": "step",
            "goal": "Reach the main menu",
            "expected_results": [
              { "expected": "the main menu is visible" },
              { "expected": "no loading spinner remains on screen" }
            ],
            "finish_condition": "1. the main menu is visible\n2. no loading spinner remains on screen",
            "screenshots": 1,
            "pause_game": false,
            "performance_monitoring": false,
            "hint_manual": []
          }
        },
        "item_order": ["1"]
      }
    },
    "player_order": ["1"]
  }
  ```

  ```json 404 Not Found theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  {
    "error": "test not found"
  }
  ```
</ResponseExample>


## OpenAPI

````yaml GET /project/{projectId}/tests/{testId}
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}/tests/{testId}:
    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:
        - Tests
      summary: Get Test
      description: Retrieve a single test case, optionally by version.
      operationId: getTest
      parameters:
        - name: testId
          in: path
          required: true
          description: The test ID (UUID)
          schema:
            type: string
            format: uuid
        - name: version
          in: query
          description: Specific version (positive integer)
          schema:
            type: integer
            minimum: 1
        - name: include_shared_collection_steps
          in: query
          description: Whether shared collection steps are expanded inline
          schema:
            type: boolean
            default: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestCase'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Test not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    TestCase:
      type: object
      description: >-
        Full test case body. Shape varies by test_type (verification, discovery,
        task); see the docs page for the exact shape.
      properties:
        id:
          type: string
          format: uuid
        project_id:
          type: string
        name:
          type: string
        version:
          type: integer
        tags:
          type: array
          items:
            type: string
        incident_auto_approve:
          type: boolean
        test_type:
          type: string
          enum:
            - verification
            - discovery
            - task
        quarantined:
          type: boolean
        testrail:
          type: object
          nullable: true
        source:
          type: string
          enum:
            - repository
            - bot
        min_seconds:
          type: integer
          minimum: 0
          maximum: 19800
          description: >-
            Test-level minimum runtime in seconds. Allowed for `discovery` and
            `task` only; sending this on a `verification` test is rejected with
            400. Defaults when omitted: discovery=3600 (1h), task=0. Must be ≤
            `max_seconds` (validated against the effective budget after defaults
            are applied).
        max_seconds:
          type: integer
          minimum: 0
          maximum: 19800
          description: >-
            Test-level maximum runtime in seconds. Hard ceiling for any single
            run is 19800 (5.5h). Defaults when omitted: verification=19800
            (5.5h), discovery=10800 (3h), task=19800 (5.5h).
        players_by_key:
          type: object
          additionalProperties: true
        player_order:
          type: array
          items:
            type: string
    Error:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
        details:
          type: object
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: API key for authentication

````