---
title: Run Test Plan
slug: suite-documentation/2VAj-run-test-plan
docTags: 
createdAt: 2026-06-04T11:48:36.995Z
---

### Endpoint Information

- **URL**:\<your-gateway-url>/queue
- **Method**: `POST`
- **Authentication**: Required (`Bearer Token`)

### Request Body

```javascript
{
  "planId": 681,
  "userId": 1,
  "forceRun": false,
  "schedulerTriggered": false
}
```

### Request Body Parameters

| Parameter          | Type      | Required | Description                                                                                                                                                                                                       |
| ------------------ | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `planId`           | `Long`    | Yes      | The unique ID of the test plan to execute.                                                                                                                                                                        |
| userId             | `Long`    | Yes      | The unique ID of the user who runs plan.                                                                                                                                                                          |
| forceRun           | `Boolean` | Yes      | Indicates whether the plan should be forced to run. When <br />true<br />, the run request bypasses the normal already-running confirmation flow and starts the plan as a forced execution. Default: <br />false. |
| schedulerTriggered | `Boolean` | Yes      | Indicates whether the run request was triggered by the scheduler instead of a manual user action. Used for scheduled plan executions. Default: false.                                                             |

### Request Headers

| Header        | Required | Description                                                                                                                   |
| ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Authorization | Yes      | Bearer token used to authenticate the request. Format: Bearer \<your\_access\_token>.                                         |
| Content-Type  | Yes      | Must be application/json.                                                                                                     |
| X-Company-Id  | Yes      | The company context for the request. The gateway uses this value to route and authorize the request for the selected company. |

### Response

This response indicates that the run request was accepted successfully. The API returns an empty JSON object and does not include additional response data.

```javascript
{}
```

### Response Fields

| Parameter | Type   | Description                                                                                           |
| --------- | ------ | ----------------------------------------------------------------------------------------------------- |
| \{}       | Object | Empty response body. A <br />200 OK status indicates that the run request was processed successfully. |

### Error Codes

| HTTP Code | Error Message           | Description                                                                                                                 |
| --------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `400`     | `BAD_REQUEST`           | Request body is invalid, required fields are missing, or the plan cannot be started because of a business validation error. |
| `401`     | `UNAUTHORIZED`          | Bearer token is missing, invalid, or expired.                                                                               |
| `403`     | `FORBIDDEN`             | The user is authenticated but does not have permission to run the plan or access the company.                               |
| `404`     | `NOT_FOUND`             | The requested route or referenced resource could not be found.                                                              |
| `500`     | `INTERNAL_SERVER_ERROR` | An unexpected error occurred on the server side.                                                                            |
| `503`     | `SERVICE_UNAVAILABLE`   | Gateway cannot reach the queue service or an upstream service is unavailable.                                               |

### Application Error Codes

| Code  | HTTP Status | Source  | Meaning                                                     |
| ----- | ----------- | ------- | ----------------------------------------------------------- |
| 10000 | 404         | Queue   | Plan not found                                              |
| 10002 | 404         | Queue   | User not found                                              |
| 10013 | 422         | Queue   | Plan has no scenarios                                       |
| 10001 | 404         | Queue   | Plan has no environment                                     |
| 10004 | 410         | Queue   | Entity is not enabled, örn. plan inactive                   |
| 10005 | 410         | Queue   | Entity is deleted                                           |
| 10012 | 409         | Queue   | Plan is already running                                     |
| 10008 | 422         | Queue   | Environment is not registered; errorType is CONFIRMATION    |
| 10007 | 422         | Queue   | App file is missing for mobile plan                         |
| 10014 | 422         | Queue   | Build is not assigned                                       |
| 20005 | 400         | Common  | Request body validation error, örn. missing planId / userId |
| 10001 | 401         | Gateway | Authentication required                                     |
| 10002 | 401         | Gateway | Invalid token                                               |
| 10003 | 403         | Gateway | No permission                                               |
| 10004 | 400         | Gateway | Missing or malformed X-Company-Id                           |
| 10008 | 503         | Gateway | Routed service unavailable                                  |

### Example Request

```javascript
curl --location '{gateway-url}/queue' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'X-Company-Id: <company_id>' \
  --data '{
    "planId": <plan_id>,
    "userId": <user_id>,
    "forceRun": false,
    "schedulerTriggered": false
  }'
```