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

# Get Run Status API

> Check test run status and retrieve results programmatically

Check test run status and retrieve detailed results programmatically. This endpoint enables **blocking mode** in CI/CD pipelines, custom post-run automation, and integration with your existing tooling.

## When to Use This API

* **Test result analysis** – Build dashboards or generate reports from test results
* **Custom post-run automation** – Trigger webhooks, custom alerting, or auto-create tickets
* **CI/CD blocking mode** – Wait for test completion before proceeding with deployments (GitLab, CircleCI, Jenkins, etc.)

For detailed examples, see:

* **[GitLab CI Blocking Mode](/configuration/gitlab#blocking-mode)** – Complete GitLab CI/CD example
* **[CI/CD Integration](/configuration/ci-cd-integration)** – Advanced use cases including webhooks and custom automation

## Quick Example: Polling Script

Basic polling example:

```bash theme={null}
RESPONSE=$(curl -s "https://api.qa.tech/v1/run/$SHORT_ID" \
  -H "Authorization: Bearer $QATECH_API_TOKEN")

STATUS=$(echo "$RESPONSE" | jq -r '.status')

if [[ "$STATUS" == "COMPLETED" || "$STATUS" == "ERROR" || "$STATUS" == "CANCELLED" ]]; then
  RESULT=$(echo "$RESPONSE" | jq -r '.result')
  if [[ "$RESULT" == "PASSED" ]]; then
    echo "Tests passed!"
  else
    echo "Tests failed: $RESULT"
  fi
else
  echo "Status: $STATUS - still running"
fi
```

**Variables:**

* `$SHORT_ID` – The run short ID (returned from [Start Run API](/api-reference/start-run) response: `run.shortId`)
* `$QATECH_API_TOKEN` – Your project's API token (found in **Settings → Integrations → API**)

## API Reference

### Endpoint

```
GET /run/{shortId}
```

**Base URL:** `https://api.qa.tech/v1`

### Query Parameters

| Parameter   | Type   | Required | Description                                                                                                                                                                                                        |
| ----------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `testCases` | string | No       | Controls which test cases are run. Use `failed` to include only failed/skipped/error test cases, or `all` to include all test cases with full details. When omitted, `runTestCases` is returned as an empty array. |

### Authentication

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

```
Authorization: Bearer YOUR_API_TOKEN
```

You can obtain your project's API token from the QA.tech dashboard in **Settings → Integrations → API**.

### Path Parameters

| Parameter | Type   | Required | Description                                                          |
| --------- | ------ | -------- | -------------------------------------------------------------------- |
| `shortId` | string | Yes      | The short ID of the run (returned from Start Run API: `run.shortId`) |

### Response Format

#### Success Response (200)

With `?testCases=all` or `?testCases=failed`:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "shortId": "abc123",
  "status": "COMPLETED",
  "result": "FAILED",
  "runTestCases": [
    {
      "id": "test-case-uuid",
      "shortId": "xyz789",
      "name": "Login flow test",
      "status": "COMPLETED",
      "result": "FAILED",
      "resultTitle": "Could not find login button",
      "evaluationThought": "The test failed because the login button was not visible on the page.",
      "promptGoal": "Test the login flow",
      "promptExamples": null
    }
  ]
}
```

Without `testCases` query param, the response has the same top-level fields but **no** `runTestCases` array (or it is empty).

#### Response Fields

| Field          | Type           | Description                                                                       |
| -------------- | -------------- | --------------------------------------------------------------------------------- |
| `id`           | string (UUID)  | Internal run identifier                                                           |
| `shortId`      | string         | Run short ID used in URLs                                                         |
| `status`       | string         | Current run status (see Status Values below)                                      |
| `result`       | string \| null | Test result when status is `COMPLETED` (see Result Values below)                  |
| `runTestCases` | array          | Present when `?testCases=failed` or `?testCases=all`. Array of test case results. |

#### Run Test Case Fields

| Field               | Type           | Description                           |
| ------------------- | -------------- | ------------------------------------- |
| `id`                | string (UUID)  | Test case identifier                  |
| `shortId`           | string         | Test case short ID                    |
| `name`              | string         | Test case name                        |
| `status`            | string         | Test case status                      |
| `result`            | string \| null | Test result (e.g. `FAILED`, `PASSED`) |
| `resultTitle`       | string \| null | Brief failure/summary title           |
| `evaluationThought` | string \| null | Detailed explanation                  |
| `promptGoal`        | string \| null | Original test goal                    |
| `promptExamples`    | string \| null | Example scenarios used                |

### Status Values

| Status      | Description                          |
| ----------- | ------------------------------------ |
| `INITIATED` | Run has been created but not started |
| `RUNNING`   | Tests are currently executing        |
| `COMPLETED` | All tests have finished              |
| `ERROR`     | Run encountered an error             |
| `CANCELLED` | Run was cancelled                    |

### Result Values

| Result    | Description                                                   |
| --------- | ------------------------------------------------------------- |
| `PASSED`  | All tests passed                                              |
| `FAILED`  | One or more tests failed                                      |
| `SKIPPED` | Tests were skipped                                            |
| `null`    | Run is still in progress (status is `INITIATED` or `RUNNING`) |

## Error Handling

| Status  | Description                 |
| ------- | --------------------------- |
| **400** | Invalid query parameters.   |
| **401** | Missing or invalid API key. |
| **403** | Organization suspended.     |
| **404** | Run or project not found.   |

Responses can include a body such as: `{ "message": "..." }`.

## Related Documentation

* **[Start Run API](/api-reference/start-run)** – Trigger test runs programmatically
* **[Rerun Tests](/api-reference/rerun)** – Rerun all or failed tests from a run
* **[CI/CD Integration](/configuration/ci-cd-integration)** – Overview of integration modes and advanced use cases
* **[GitLab CI](/configuration/gitlab)** – GitLab-specific integration examples with blocking mode