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

# Retrieve Test Cases

> Get test cases for a prompt

Retrieve test cases for a specific prompt. This endpoint returns test cases associated with the given prompt ID, with options to filter by prompt version and include generation data.

## Retrieve Test Cases

<CodeGroup>
  ```typescript theme={null}
  const API_KEY = process.env.TELA_API_KEY;
  const promptId = 'prompt_uuid';

  // Optional parameters
  const promptVersionIds = ['version_uuid1', 'version_uuid2']; // Optional
  const includeGenerations = true; // Optional

  // Build URL with query parameters
  const url = new URL('https://api.tela.ai/test-case');
  url.searchParams.append('promptId', promptId);

  // Add optional parameters if provided
  if (promptVersionIds.length > 0) {
    promptVersionIds.forEach(id => url.searchParams.append('promptVersionIds', id));
  }
  if (includeGenerations) {
    url.searchParams.append('includeGenerations', 'true');
  }

  const response = await fetch(url, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    }
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python theme={null}
  import requests

  API_KEY = os.getenv('TELA_API_KEY')
  prompt_id = 'prompt_uuid'

  # Optional parameters
  prompt_version_ids = ['version_uuid1', 'version_uuid2']  # Optional
  include_generations = True  # Optional

  params = {
      'promptId': prompt_id
  }

  # Add optional parameters if provided
  if prompt_version_ids:
      params['promptVersionIds'] = prompt_version_ids
  if include_generations:
      params['includeGenerations'] = 'true'

  response = requests.get(
      'https://api.tela.ai/test-case',
      headers={
          'Authorization': f'Bearer {API_KEY}',
          'Content-Type': 'application/json'
      },
      params=params
  )

  print(response.json())
  ```

  ```javascript theme={null}
  const API_KEY = process.env.TELA_API_KEY;
  const promptId = 'prompt_uuid';

  // Optional parameters
  const promptVersionIds = ['version_uuid1', 'version_uuid2']; // Optional
  const includeGenerations = true; // Optional

  // Build URL with query parameters
  const url = new URL('https://api.tela.ai/test-case');
  url.searchParams.append('promptId', promptId);

  // Add optional parameters if provided
  if (promptVersionIds.length > 0) {
    promptVersionIds.forEach(id => url.searchParams.append('promptVersionIds', id));
  }
  if (includeGenerations) {
    url.searchParams.append('includeGenerations', 'true');
  }

  fetch(url, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    }
  })
  .then(response => response.json())
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error('Error:', error);
  });
  ```
</CodeGroup>

### Parameters

| Name                 | Type      | Required | Description                                                                      |
| -------------------- | --------- | -------- | -------------------------------------------------------------------------------- |
| `promptId`           | string    | Yes      | The UUID of the prompt to retrieve test cases for                                |
| `promptVersionIds`   | string\[] | No       | Optional array of prompt version UUIDs to filter test cases by specific versions |
| `includeGenerations` | boolean   | No       | Whether to include generation data in the response                               |

### Response

The response returns an array of test case objects with the following properties:

| Field                  | Type           | Description                                                     |
| ---------------------- | -------------- | --------------------------------------------------------------- |
| `id`                   | string         | Unique identifier for the test case (UUID)                      |
| `title`                | string         | Title of the test case                                          |
| `messages`             | array or null  | Array of message objects with role and content                  |
| `variables`            | object or null | Key-value pairs of variables used in the test case              |
| `variablesRichContent` | object or null | Key-value pairs of rich content variables                       |
| `files`                | array or null  | Array of file objects attached to the test case                 |
| `promptId`             | string         | UUID of the prompt this test case belongs to                    |
| `expectedOutput`       | string or null | Expected output for evaluation purposes                         |
| `answers`              | object or null | Evaluation answers with good/bad results and evals              |
| `promptApplicationId`  | string or null | UUID of the prompt application if applicable                    |
| `metadata`             | object or null | Metadata about the test case including source                   |
| `createdAt`            | string         | Creation timestamp                                              |
| `updatedAt`            | string         | Last update timestamp                                           |
| `deletedAt`            | string or null | Deletion timestamp if applicable                                |
| `generations`          | array          | Array of generations (only included if includeGenerations=true) |

#### Example Response

```json theme={null}
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Customer Support Query Test",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful customer support assistant."
      },
      {
        "role": "user",
        "content": "My order hasn't arrived yet."
      }
    ],
    "variables": {
      "customer_name": "John Doe",
      "order_id": "ORD-12345"
    },
    "variablesRichContent": null,
    "files": null,
    "promptId": "550e8400-e29b-41d4-a716-446655440001",
    "expectedOutput": "I'll help you track down your order, John. Let me look up order ORD-12345 for you.",
    "answers": {
      "version1": {
        "good": [],
        "bad": [],
        "evals": []
      }
    },
    "promptApplicationId": null,
    "metadata": {
      "source": "craft"
    },
    "createdAt": "2023-01-01T00:00:00.000Z",
    "updatedAt": "2023-01-02T00:00:00.000Z",
    "deletedAt": null,
    "generations": []
  }
]
```


## OpenAPI

````yaml GET /test-case
openapi: 3.0.1
info:
  title: Tela API
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.tela.com
security: []
paths:
  /test-case:
    get:
      description: Retrieve test cases for a prompt
      parameters:
        - name: promptId
          in: query
          required: true
          schema:
            type: string
        - name: promptVersionIds
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
        - name: includeGenerations
          in: query
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: List of test cases
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TestCaseResponse'
components:
  schemas:
    TestCaseResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the test case
        title:
          type: string
          description: Title of the test case
        messages:
          type: array
          nullable: true
          description: Array of message objects with role and content
          items:
            type: object
            properties:
              role:
                type: string
                enum:
                  - user
                  - system
                  - assistant
                  - function
                  - developer
                description: The role of the message sender
              content:
                description: The content of the message
                oneOf:
                  - type: string
                  - type: object
                    additionalProperties: true
            required:
              - role
              - content
        variables:
          type: object
          nullable: true
          description: Key-value pairs of variables used in the test case
          additionalProperties:
            type: string
        variablesRichContent:
          type: object
          nullable: true
          description: Key-value pairs of rich content variables
          additionalProperties:
            type: string
        files:
          type: array
          nullable: true
          description: Array of file objects attached to the test case
          items:
            type: object
            properties:
              index:
                type: number
                description: Index of the file in the array
              name:
                type: string
                description: Name of the file
              mimeType:
                type: string
                description: MIME type of the file
              vaultUrl:
                type: string
                description: URL to the file in the vault
              variableName:
                type: string
                description: Variable name associated with the file
              url:
                type: string
                description: Public URL to the file
            required:
              - index
              - name
              - mimeType
              - vaultUrl
              - variableName
              - url
        promptId:
          type: string
          format: uuid
          description: UUID of the prompt this test case belongs to
        expectedOutput:
          type: string
          nullable: true
          description: Expected output for evaluation purposes
        answers:
          type: object
          nullable: true
          description: Evaluation answers with good/bad results and evals
          additionalProperties:
            type: object
            properties:
              good:
                type: array
                description: Array of good evaluation results
                items: {}
              bad:
                type: array
                description: Array of bad evaluation results
                items: {}
              evals:
                type: array
                description: Array of evaluation metrics
                items: {}
            required:
              - good
              - bad
              - evals
        promptApplicationId:
          type: string
          format: uuid
          nullable: true
          description: UUID of the prompt application if applicable
        metadata:
          type: object
          nullable: true
          description: Metadata about the test case
          properties:
            source:
              type: string
              enum:
                - workstation
                - craft
                - test-case
              description: Source of the test case
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp
        deletedAt:
          type: string
          format: date-time
          nullable: true
          description: Deletion timestamp if applicable
        generations:
          type: array
          description: Array of generations (only included if includeGenerations=true)
          items: {}
      required:
        - id
        - title
        - messages
        - variables
        - variablesRichContent
        - files
        - promptId
        - expectedOutput
        - answers
        - promptApplicationId
        - createdAt
        - updatedAt
        - deletedAt

````