Run Test Plan

13 min

Endpoint Information

URL: {gateway-url}/queue

Method: POST

Authentication: Required (Bearer Token)

Company Header: Required (X-Company-Id)

Headers

Header	Type	Required	Description
Authorization	String	Yes	Bearer token used for authentication. Example: Bearer <your_access_token>.
X-Company-Id	Long	Yes	The company ID used to scope the request.
Content-Type	String	Yes	Must be application/json.
Accept	String	No	Recommended value: application/json.

Request Body

{
  "planId": 681,
  "userId": 1,
  "forceRun": false,
  "schedulerTriggered": false,
  "description": "Triggered from API"
}

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 the plan.
forceRun	Boolean	No	Indicates whether the run should skip environment registration validation. Default value is false. This does not bypass the already-running execution control.
schedulerTriggered	Boolean	No	Indicates whether the run request was triggered by the scheduler. If true, the created execution is marked as scheduled. Default value is false.
description	String	No	Optional execution description.

Response Body

If the run request is processed successfully, the endpoint returns HTTP 200 OK with an empty JSON object.

{}

Response Fields

This endpoint does not return response fields.

The response does not include data, result.code, or result.message.

Behavior Notes

This endpoint starts a test plan execution.

The service validates the test plan by planId and the user by userId.

The plan and user lookup are scoped by X-Company-Id.

The plan must be enabled and not deleted.

The plan must have at least one scenario.

The plan must have at least one active environment when the selected execution type requires an environment.

If another execution is already active for the same plan, the request fails with conflict.

If forceRun is false, the service validates whether selected environments are registered/available for execution.

If forceRun is true, environment registration validation is skipped.

forceRun does not skip the already-running execution control.

If schedulerTriggered is true, the created test execution is marked as scheduled.

For Enterprise project type, build-service validation is skipped by the queue service.

For non-Enterprise project type, a build must be assigned before execution.

Error Response Format

Error responses use the common problem detail format.

{
  "instance": "/queue",
  "status": 404,
  "title": "Not Found",
  "type": "https://errors.testinium.com/exception",
  "timestamp": "2026-08-27T07:12:26.871905643Z",
  "errorType": "EXCEPTION",
  "errors": {
    "code": 10000,
    "message": "Plan with id 681 not found!"
  }
}

Validation Error Response Example

{
  "instance": "/queue",
  "status": 400,
  "title": "Bad Request",
  "type": "https://errors.testinium.com/validation",
  "timestamp": "2026-08-27T07:12:26.871905643Z",
  "errorType": "VALIDATION",
  "errors": [
    {
      "code": 20005,
      "message": "must not be null",
      "field": "planId"
    }
  ]
}

Confirmation Error Response Example

This response can be returned when selected environments are not registered and forceRun is false.

{
  "instance": "/queue",
  "status": 422,
  "title": "Unprocessable Entity",
  "type": "https://errors.testinium.com/confirmation",
  "timestamp": "2026-08-27T07:12:26.871905643Z",
  "errorType": "CONFIRMATION",
  "errors": {
    "code": 10008,
    "message": "Environment is not registered"
  }
}

Error Codes

HTTP Code	Error Message	Description
400	BAD_REQUEST	The request body is invalid, required fields are missing, or a required header is missing.
401	UNAUTHORIZED	Authentication failed, authentication is required, or the token is invalid.
403	FORBIDDEN	The user does not have permission to access the requested company or resource.
404	NOT_FOUND	The requested plan, user, plan environment, test result, or test execution could not be found.
409	CONFLICT	The test plan already has an active execution.
410	GONE	The requested plan or related entity is disabled or deleted.
422	UNPROCESSABLE_ENTITY	The plan cannot be executed because required execution data is missing or invalid.
503	SERVICE_UNAVAILABLE	The queue service or a downstream service is unavailable.
500	INTERNAL_SERVER_ERROR	An unexpected error occurred on the server side.

Application Error Codes

Code	Error Type	HTTP Code	Source	Description
10000	EXCEPTION	404	Queue	The requested test plan could not be found.
10001	EXCEPTION	404	Queue	The test plan has no active environment.
10002	EXCEPTION	404	Queue	The requested user could not be found or does not have company access.
10004	EXCEPTION	410	Queue	The requested entity is not enabled.
10005	EXCEPTION	410	Queue	The requested entity is deleted.
10007	EXCEPTION	422	Queue	Required mobile app file is missing for the plan.
10008	CONFIRMATION	422	Queue	One or more selected environments are not registered.
10012	EXCEPTION	409	Queue	The test plan already has an active execution.
10013	EXCEPTION	422	Queue	The test plan has no scenarios.
10014	EXCEPTION	422	Queue	Build is not assigned. Applies to non-Enterprise project type.
20005	VALIDATION	400	Common	Request body validation failed. For example, planId or userId is missing.
20009	EXCEPTION	405	Common	The HTTP method is not supported.
90003	EXCEPTION	4xx / 5xx	Common	A downstream service failed to process the request.
10000	EXCEPTION	401	Gateway	Authentication failed.
10001	EXCEPTION	401	Gateway	Authentication is required to access this resource.
10002	EXCEPTION	401	Gateway	The provided token is invalid.
10003	EXCEPTION	403	Gateway	The user is not authorized for the requested resource.
10004	EXCEPTION	400	Gateway	A required header is missing. For example, X-Company-Id is not provided.
10005	EXCEPTION	401	Gateway	A required token claim is missing.
10007	EXCEPTION	403	Gateway	The user does not have access to the requested resource.
10008	EXCEPTION	503	Gateway	The routed queue service is unavailable.

Example Request

curl --location '{gateway-url}/queue' \
--header 'Accept: application/json' \
--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,
  "description": "Triggered from API"
}'

Example Force Run Request

curl --location '{gateway-url}/queue' \
--header 'Accept: application/json' \
--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": true,
  "schedulerTriggered": false,
  "description": "Forced from API"
}'