Use the following API methods to request details about tests (individual instances of test cases added to specific test runs or test plans).
get_test
Returns an existing test.
GET index.php?/api/v2/get_test/{test_id}Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| test_id | integer | true | The ID of the test |
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 using query parameters in the request URL:
| Name | Type | Description |
|---|---|---|
| with_data | string | The parameter to get data |
Response content
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 | integer | The ID of the user the test is assigned to |
| case_id | integer | 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 estimated forecast of the related test case, e.g. “30s” or “1m 45s” |
| id | integer | The unique ID of the test |
| milestone_id | integer | The ID of the milestone that is linked to the test case |
| priority_id | integer | 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 | integer | The ID of the test run the test belongs to |
| status_id | integer | The ID of the current status of the test, also see get_statuses |
| title | string | The title of the related test case |
| type_id | integer | 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
| Status Code | Description |
|---|---|
| 200 | Success (the test is returned as part of the response) |
| 400 | Invalid or unknown test case |
| 403 | No access to the project |
| 429 | TestRail Cloud only—Too many requests (see API rate limit) |
get_tests
Returns a list of tests for a test run.
GET index.php?/api/v2/get_tests/{run_id}Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| run_id | integer | true | 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 using query parameters in the request URL:
| Name | Type | Description |
|---|---|---|
| status_id | integer (list) | A comma-separated list of status IDs to filter by |
| limit | integer | The 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 | integer (list) | The 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&offset=1&limit=30&status_id=4,5Response 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
| Status Code | Description |
|---|---|
| 200 | Success (the tests are returned as part of the response) |
| 400 | Invalid or unknown test run |
| 403 | No access to the project |
| 429 | TestRail Cloud only—Too many requests (see API rate limit) |