API: Statuses - TestRail

API: Statuses

Use the following API methods to request details about test statuses.

API Rate Limit

Please note that the API is rate-limited on TestRail Cloud to ensure optimal performance for all users and may throttle requests. TestRail might also return a 429 Too Many Requests response, which you are expected to handle. Such a response also includes a Retry-After header indicating how many seconds to wait before you are allowed to submit the next request.

To avoid rate limits on TestRail Cloud, try using bulk API endpoints (e.g. using as add_results_for_cases instead of add_results_for case), build a time delay into your API calls, or upgrade to TestRail Enterprise Cloud.

Rate limits for TestRail Cloud are as follows:

  • 180 Requests per instance, per minute for TestRail Cloud Professional subscriptions.
  • 300 Requests per instance, per minute for TestRail Cloud Enterprise subscriptions.

No API rate limits are built into TestRail Server installations.

get_statuses

 Returns a list of available test statuses.

GET index.php?/api/v2/get_statuses

Response content

The returned response includes all system and custom statuses in the following format:

[
	{
		"color_bright": 12709313,
		"color_dark": 6667107,
		"color_medium": 9820525,
		"id": 1,
		"is_final": true,
		"is_system": true,
		"is_untested": false,
		"label": "Passed",
		"name": "passed"
	},
	..
	{
		"color_bright": 16631751,
		"color_dark": 14250867,
		"color_medium": 15829135,
		"id": 5,
		"is_final": true,
		"is_system": true,
		"is_untested": false,
		"label": "Failed",
		"name": "failed"
	},
	{
		"color_bright": 13684944,
		"color_dark": 0,
		"color_medium": 10526880,
		"id": 6,
		"is_final": false,
		"is_system": false,
		"is_untested": false,
		"label": "Custom",
		"name": "custom_status1"
	}
]

Each status has a unique ID, a name (system name) as well as a label (display name). The color related fields specify the different colors used for a status and are RGB colors. The following system statuses are available by default. You can add additional custom statuses under Administration > Customizations in TestRail.

ID Name
1 Passed
2 Blocked
3 Untested
4 Retest
5 Failed

Response codes

200 Success, the available statuses are returned as part of the response