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

# List Test Cases API

> Retrieve test cases from your project programmatically

List and filter test cases in your project. Use this endpoint to retrieve test cases for reporting, syncing with external systems, or building custom dashboards.

* **Endpoint**: `GET /test-cases`
* **Authentication**: Bearer token (project API token)
* **Base URL**: `https://api.qa.tech/v1`

<Note>
  The test case `id` (UUID) is used when creating tests with dependencies or running specific test cases via the [Rerun API](/api-reference/rerun). For most run operations, use test plans instead of individual test case IDs.
</Note>

## Authentication

Include your project's API token in the `Authorization` header:

```
Authorization: Bearer YOUR_API_TOKEN
```

Find your API token in the QA.tech dashboard: **Settings → Integrations → API**.

## Query Parameters

All parameters are optional. Use them to filter and paginate results:

| Parameter            | Type    | Description                                            |
| -------------------- | ------- | ------------------------------------------------------ |
| `applicationShortId` | string  | Filter by application (e.g. `app_gXeBl2`)              |
| `labels`             | string  | Filter by labels (comma-separated, e.g. `smoke,login`) |
| `isEnabled`          | boolean | Filter by enabled status (`true` or `false`)           |
| `limit`              | integer | Maximum number of results to return                    |
| `offset`             | integer | Number of results to skip (for pagination)             |

## Response Format

### Success (200)

```json theme={null}
{
  "testCases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Login Flow Test",
      "isEnabled": true,
      "labels": ["smoke", "auth"],
      "classification": "functional",
      "applicationShortId": "app_gXeBl2",
      "applicationName": "Main Web App",
      "goal": "Verify users can log in with valid credentials",
      "createdAt": "2026-01-15T10:30:00.000Z"
    },
    {
      "id": "661f9500-f3a2-52e5-b827-557766550111",
      "name": "Checkout Process",
      "isEnabled": true,
      "labels": ["critical", "e2e"],
      "classification": "functional",
      "applicationShortId": "app_gXeBl2",
      "applicationName": "Main Web App",
      "goal": "Complete a purchase from cart to confirmation",
      "createdAt": "2026-02-20T14:15:00.000Z"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}
```

### Response Fields

| Field       | Type    | Description                         |
| ----------- | ------- | ----------------------------------- |
| `testCases` | array   | Array of test case objects          |
| `total`     | integer | Total number of matching test cases |
| `limit`     | integer | Applied limit value                 |
| `offset`    | integer | Applied offset value                |

### Test Case Fields

| Field                | Type           | Description                               |
| -------------------- | -------------- | ----------------------------------------- |
| `id`                 | string (UUID)  | Test case identifier                      |
| `name`               | string         | Test case name                            |
| `isEnabled`          | boolean        | Whether the test is enabled in test plans |
| `labels`             | array          | Array of label strings                    |
| `classification`     | string         | Test classification (e.g. `functional`)   |
| `applicationShortId` | string         | Associated application short ID           |
| `applicationName`    | string         | Associated application name               |
| `goal`               | string \| null | Test goal/objective                       |
| `createdAt`          | string         | ISO 8601 creation timestamp               |

## Example Requests

### List All Test Cases

```bash theme={null}
curl "https://api.qa.tech/v1/test-cases" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

### Filter by Application

```bash theme={null}
curl "https://api.qa.tech/v1/test-cases?applicationShortId=app_gXeBl2" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

### Filter by Labels

```bash theme={null}
curl "https://api.qa.tech/v1/test-cases?labels=smoke,critical" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

### List Only Enabled Tests

```bash theme={null}
curl "https://api.qa.tech/v1/test-cases?isEnabled=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

### Paginated Request

```bash theme={null}
curl "https://api.qa.tech/v1/test-cases?limit=10&offset=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

### Combined Filters

```bash theme={null}
curl "https://api.qa.tech/v1/test-cases?applicationShortId=app_gXeBl2&isEnabled=true&labels=smoke&limit=50" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

## Error Responses

| Status  | Description                             |
| ------- | --------------------------------------- |
| **400** | Invalid query parameters                |
| **401** | Missing or invalid API key              |
| **403** | Invalid token or organization suspended |
| **404** | Project not found                       |
| **500** | Server error                            |

Error responses include a body: `{ "message": "Error description" }`.

## Related

* [Create Test Case API](/api-reference/test-cases) – Create test cases programmatically
* [Start Run API](/api-reference/start-run) – Trigger test runs
* [API Introduction](/api-reference/introduction) – Authentication and ID reference