Rerun Test Plan

10 min

The endpoint allows the user to rerun specific scenarios of a test plan.

Endpoint Information

URL: {gateway-url}/queue/rerun

Method: POST

Authentication: Required (Bearer Token)

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	Company context for the request. The authenticated user must have access to this company.

Request Body

{
  "planId": 704,
  "userId": 1,
  "frameworkType": "SELENIUM4",
  "forceRun": false,
  "scenarioEnvironmentPairs": [
    {
      "scenarioId": 4267,
      "environmentId": 2001
    }
  ]
}

Request Body Parameters

Parameter	Type	Required	Description
planId	Long	Yes	The unique ID of the test plan to rerun.
userId	Long	Yes	The unique ID of the user who triggers the rerun.
frameworkType	String	Yes	Test framework type. Allowed values: SELENIUM, SELENIUM4, APPIUM, APPIUM2, SERVICE, PLAYWRIGHT.
forceRun	Boolean	No	Indicates whether the rerun should be forced. Default: false.
scenarioEnvironmentPairs	Array	Yes	List of scenario/environment pairs to rerun. Must contain at least one item.
scenarioEnvironmentPairs[].scenarioId	Long	Yes	The unique ID of the scenario to rerun.
scenarioEnvironmentPairs[].environmentId	Long	Conditional	Required for SELENIUM, SELENIUM4, APPIUM, and APPIUM2. Optional for SERVICE and PLAYWRIGHT.

Response

This response indicates that the rerun request was accepted successfully. No additional response data is returned.

{}

Error Response Format

{
"instance": "/queue/rerun",
"status": 404,
"title": "Not Found",
"type": "https://errors.testinium.com/exception",
"timestamp": "2026-08-18T12:08:41.165927056Z",
"errorType": "EXCEPTION",
"errors": {
"code": 10002,
"message": "User with id 1666666 not found!"
}

Error Response Fields

Parameter	Type	Description
instance	String	The request path where the error occurred.
status	Integer	HTTP status code.
title	String	Short HTTP error title.
type	String	Error type reference URL.
timestamp	String	Error timestamp in UTC.
errorType	String	Internal error category, such as EXCEPTION, VALIDATION, or CONFIRMATION.
errors	Object or Array	Application-level error details. Validation errors may be returned as an array.
errors.code	Integer	Application-specific error code.
errors.message	String	Human-readable error message. This may be localized based on request language.
errors.field	String	Field related to the error. This field may not always be returned.

Error Codes

HTTP Code	Error Message	Description
400	BAD_REQUEST	Request body is invalid, malformed, or contains validation errors.
401	UNAUTHORIZED	Bearer token is missing, invalid, or expired.
403	FORBIDDEN	The authenticated user does not have permission to access the resource.
404	NOT_FOUND	A referenced resource, such as plan or user, could not be found.
409	CONFLICT	The plan is already running.
410	GONE	A referenced entity is disabled or deleted.
422	UNPROCESSABLE_ENTITY	The request is syntactically valid but cannot be processed due to business rules.
500	INTERNAL_SERVER_ERROR	An unexpected server-side error occurred.
503	SERVICE_UNAVAILABLE	Gateway or an upstream service is unavailable.

Application Error Codes

Code	HTTP Status	Source	Description
10000	404	Queue	Plan not found.
10002	404	Queue	User not found.
10013	422	Queue	No scenarios are associated with this plan.
10001	404	Queue	No environment is associated with this plan.
10004	410	Queue	Entity is not enabled.
10005	410	Queue	Entity is deleted.
10012	409	Queue	Plan is already running.
10008	422	Queue	Environment is not registered. Returned with errorType: CONFIRMATION.
10007	422	Queue	Required app file is missing for the project.
10014	422	Queue	No build is assigned to the plan.
20005	400	Common	Request body validation error, such as missing planId, userId, frameworkType, or scenarioEnvironmentPairs.
10001	401	Gateway	Authentication is required.
10002	401	Gateway	Token is invalid or malformed.
10003	403	Gateway	User does not have permission to access the resource.
10004	400	Gateway	Required X-Company-Id header is missing or malformed.
10008	503	Gateway	Routed service is unreachable.

Note: Application error codes may overlap between services. Use the Source, HTTP status, and response message together when interpreting errors.

Example Request

curl --location '{{gateway-url}}/queue/rerun' 
--header 'Content-Type: application/json' 
--header 'Authorization: Bearer <your_access_token>' 
--header 'X-Company-Id: <company_id>' 
--data '{
"planId": <plan_id>,
"userId": <user_id>,
"frameworkType": "SELENIUM4",
"forceRun": false,
"scenarioEnvironmentPairs": [
{
"scenarioId": <scenario_id>,
"environmentId": <environment_id>
}
]
}'