API: Tests - TestRail

API: Tests

Use the following API methods to request details about tests.

On this page:

    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_test

     Returns an existing test.

    GET index.php?/api/v2/get_test/:test_id
    :test_id The ID of the test
    :with_data The parameter to get data (This is optional)

    If you are interested in the test results rather than the tests, please see get_results instead.

    Response content

    Please see below for a typical example response:

    {
	"assignedto_id": 1,
	"case_id": 1,
	"custom_expected": "..",
	"custom_preconds": "..",
	"custom_steps_separated": [
		{
			"content": "Step 1",
			"expected": "Expected Result 1"
		},
		{
			"content": "Step 2",
			"expected": "Expected Result 2"
		}
	],
	"estimate": "1m 5s",
	"estimate_forecast": null,
	"id": 100,
	"priority_id": 2,
	"run_id": 1,
	"status_id": 5,
	"title": "Verify line spacing on multi-page document",
	"type_id": 4
}

    The following system fields are always included in the response:

    Name Type Description
    assignedto_id int The ID of the user the test is assigned to
    case_id int The ID of the related test case
    estimate timespan The estimate of the related test case, e.g. “30s” or “1m 45s”
    estimate_forecast timespan The estimate forecast of the related test case, e.g. “30s” or “1m 45s”
    id int The unique ID of the test
    milestone_id int The ID of the milestone that is linked to the test case
    priority_id int The ID of the priority that is linked to the test case
    refs string A comma-separated list of references/requirements that are linked to the test case
    run_id int The ID of the test run the test belongs to
    status_id int The ID of the current status of the test, also see get_statuses
    title string The title of the related test case
    type_id int The ID of the test case type that is linked to the test case

    Custom fields of test cases are also included in the response and use their system name prefixed with ‘custom_’ as their field identifier. Please see add_case for a full list of available custom field types.

    Response codes

    200 Success, the test is returned as part of the response
    400 Invalid or unknown test
    403 No access to the project

    get_tests

    Returns a list of tests for a test run

    GET index.php?/api/v2/get_tests/:run_id
         limit=:limit
        &offset=:offset
    :run_id The ID of the test run

     

    If you are interested in the test results rather than the tests, please see get_results instead.

    Request filters

    The following filters can be applied:

    Name Type Description
    :status_id int (list) A comma-separated list of status IDs to filter by.
    :limit int Number that sets the limit of tests to be shown on the response (Optional parameter. The response size limit is 250 by default) (requires TestRail 6.7 or later)
    :offset int Number that sets the position where the response should start from (Optional parameter) (requires TestRail 6.7 or later)

     

    # All test cases for test run with ID 1 and status 4, 5 (Retest and Failed)
    GET index.php?/api/v2/get_tests/1&status_id=4,5

    Response content

    The response includes an array of tests. Each test in this list follows the same format as get_test.

     [
	{
		"id": 1, 
		"title": "Test conditional formatting with basic value range", 
		.. 
	},
	{ 
		"id": 2,
		"title": "Verify line spacing on multi-page document",
		..
	},
	..
] 

    info Please Note: As of February 26, 2021 the data structure returned by bulk GET API endpoints will change. These bulk endpoints will no longer return an array of all entities, but will instead return an object with additional pagination fields and an array of up to 250 entities.To see the new response structure and test any necessary code changes, include the following header and value in your API requests: x-api-ident: beta.

    New Response Content

    The response includes an array of tests. Each test in this list follows the same format as get_test.

    {
  "offset": 0,
  "limit": 250,
  "size": 236,
  "_links": {
    "next": null,
    "prev": null,
},
"tests": [
	{
		"id": 1, 
		"title": "Test conditional formatting with basic value range", 
		.. 
	},
	{ 
		"id": 2,
		"title": "Verify line spacing on multi-page document",
		..
	},
	..
]
}

    Response codes

    200 Success, the tests are returned as part of the response
    400 Invalid or unknown test run
    403 No access to the project