API: Results

Use the following API methods to request details about test results and to add new test results.

get_results

Returns a list of test results for a test.

GET index.php?/api/v2/get_results/:test_id

:test_id The ID of the test

Request filters

The following filters can be applied: (available since TestRail 4.0)

Name Type Description
:limit/:offset int Limit the result to :limit test results. Use :offset to skip records.
:status_id int (list) A comma-separated list of status IDs to filter by.

# The latest 10 results for test with ID 1 and statuses 4 or 5 (Retest, Failed)
GET index.php?/api/v2/get_results/1&status_id=4,5&limit=10

Response content

Please see below for a typical response:

[
	{
		"assignedto_id": 1,
		"comment": "This test failed: ..",
		"created_by": 1,
		"created_on": 1393851801,
		"custom_step_results: [
		{
			..
		},
		..
		]
		"defects": "TR-1",
		"elapsed": "5m",
		"id": 1,
		"status_id": 5,
		"test_id": 1,
		"version": "1.0RC1"
	},
	..
]

The following system fields are always included in the response:

Name Type Description
assignedto_id int The ID of the assignee (user) of the test result
comment string The comment or error message of the test result
created_by int The ID of the user who created the test result
created_on timestamp The date/time when the test result was created (as UNIX timestamp)
defects string A comma-separated list of defects linked to the test result
elapsed timespan The amount of time it took to execute the test (e.g. "1m" or "2m 30s")
id int The unique ID of the test result
status_id int The status of the test result, e.g. passed or failed, also see get_statuses
test_id int The ID of the test this test result belongs to
version string The (build) version the test was executed against

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

Response codes

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

get_results_for_case

Returns a list of test results for a test run and case combination.

The difference to get_results is that this method expects a test run + test case instead of a test. In TestRail, tests are part of a test run and the test cases are part of the related test suite. So, when you create a new test run, TestRail creates a test for each test case found in the test suite of the run. You can therefore think of a test as an “instance” of a test case which can have test results, comments and a test status. Please also see TestRail's getting started guide for more details about the differences between test cases and tests.

GET index.php?/api/v2/get_results_for_case/:run_id/:case_id

:run_id The ID of the test run
:case_id The ID of the test case

This method uses the same response format as get_results.

Request filters

The following filters can be applied: (available since TestRail 4.0)

Name Type Description
:limit/:offset int Limit the result to :limit test results. Use :offset to skip records.
:status_id int (list) A comma-separated list of status IDs to filter by.

# All results for test run with ID 1 and test case with ID 2
GET index.php?/api/v2/get_results_for_case/1/2

Response codes

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

get_results_for_run

Returns a list of test results for a test run.

Requires TestRail 4.0 or later.

GET index.php?/api/v2/get_results_for_run/:run_id

:run_id The ID of the test run

This method uses the same response format as get_results.

Request filters

The following filters can be applied:

Name Type Description
:created_after timestamp Only return test results created after this date (as UNIX timestamp).
:created_before timestamp Only return test results created before this date (as UNIX timestamp).
:created_by int (list) A comma-separated list of creators (user IDs) to filter by.
:limit/:offset int Limit the result to :limit test results. Use :offset to skip records.
:status_id int (list) A comma-separated list of status IDs to filter by.

# The latest 10 results for test run with ID 1 created by user 5
GET index.php?/api/v2/get_results_for_run/1&created_by=5&limit=10

Response codes

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

add_result

Adds a new test result, comment or assigns a test. It's recommended to use add_results instead if you plan to add results for multiple tests.

POST index.php?/api/v2/add_result/:test_id

:test_id The ID of the test the result should be added to

Request fields

The following POST fields are supported (system fields):

Name Type Description
status_id int The ID of the test status. The built-in system statuses have the following IDs:
1 Passed
2 Blocked
3 Untested (not allowed when adding a result)
4 Retest
5 Failed
You can get a full list of system and custom statuses via get_statuses.
comment string The comment / description for the test result
version string The version or build you tested against
elapsed timespan The time it took to execute the test, e.g. "30s" or "1m 45s"
defects string A comma-separated list of defects to link to the test result
assignedto_id int The ID of a user the test should be assigned to

Custom fields are supported as well and must be submitted with their system name, prefixed with 'custom_', e.g.:

{
	..
	"custom_comment": "This is a custom comment"
	..
}

The following custom field types are supported:

Name Type Description
Checkbox bool True for checked and false otherwise
Date string A date in the same format as configured for TestRail and API user (e.g. "07/08/2013")
Dropdown int The ID of a dropdown value as configured in the field configuration
Integer int A valid integer
Milestone int The ID of a milestone for the custom field
Multi-select array An array of IDs as configured in the field configuration
Step Results array An array of objects specifying the step results. Also see the example below.
String string A valid string with a maximum length of 250 characters
Text string A string without a maximum length
URL string A string with matches the syntax of a URL
User int The ID of a user for the custom field

Request example

Also see the following example which shows how to submit step results with the structured steps custom field:

{
	"status_id": 5,
	"comment": "This test failed",
	"elapsed": "15s",
	"defects": "TR-7",
	"version": "1.0 RC1 build 3724",

	..

	"custom_step_results": [
		{
			"content": "Step 1",
			"expected": "Expected Result 1",
			"actual": "Actual Result 1",
			"status_id": 1
		},
		{
			"content": "Step 2",
			"expected": "Expected Result 2",
			"actual": "Actual Result 2",
			"status_id": 2
		},

		..
	]

	..
}

Response content

If successful, this method returns the new test result using the same response format as get_results, but with a single result instead of a list of results.

Response codes

200 Success, the test result was created and is returned as part of the response
400 Invalid or unknown test
403 No permissions to add test results or no access to the project

add_result_for_case

Adds a new test result, comment or assigns a test (for a test run and case combination). It's recommended to use add_results_for_cases instead if you plan to add results for multiple test cases.

The difference to add_result is that this method expects a test run + test case instead of a test. In TestRail, tests are part of a test run and the test cases are part of the related test suite. So, when you create a new test run, TestRail creates a test for each test case found in the test suite of the run. You can therefore think of a test as an “instance” of a test case which can have test results, comments and a test status. Please also see TestRail's getting started guide for more details about the differences between test cases and tests.

POST index.php?/api/v2/add_result_for_case/:run_id/:case_id

:run_id The ID of the test run
:case_id The ID of the test case

This method supports the same POST fields as add_result.

Response content

If successful, this method returns the new test result using the same response format as get_results, but with a single result instead of a list of results.

Response codes

200 Success, the test result was created and is returned as part of the response
400 Invalid or unknown test run or case
403 No permissions to add test results or no access to the project

add_results

Adds one or more new test results, comments or assigns one or more tests. Ideal for test automation to bulk-add multiple test results in one step.

Requires TestRail 3.1 or later.

POST index.php?/api/v2/add_results/:run_id

:run_id The ID of the test run the results should be added to

This method expects an array of test results (via the 'results' field, please see below). Each test result must specify the test ID and can pass in the same fields as add_result, namely all test related system and custom fields.

Please note that all referenced tests must belong to the same test run.

Request example

The following listing shows a typical example request. In addition to the test, you need to specify at least one of the status, comment or assignee fields for each result.

{
	"results": [
		{
			"test_id": 101,
			"status_id": 5,
			"comment": "This test failed",
			"defects": "TR-7"

		},
		{
			"test_id": 102,
			"status_id": 1,
			"comment": "This test passed",
			"elapsed": "5m",
			"version": "1.0 RC1"
		},

		..

		{
			"test_id": 101,
			"assignedto_id": 5,
			"comment": "Assigned this test to Joe"
		}

		..
	]
}

Response content

If successful, this method returns the new test results using the same response format as get_results and in the same order as the list of the request.

Response codes

200 Success, the test results were created and are returned as part of the response
400 Invalid or unknown test run/tests
403 No permissions to add test results or no access to the project

add_results_for_cases

Adds one or more new test results, comments or assigns one or more tests (using the case IDs). Ideal for test automation to bulk-add multiple test results in one step.

Requires TestRail 3.1 or later.

POST index.php?/api/v2/add_results_for_cases/:run_id

:run_id The ID of the test run the results should be added to

This method expects an array of test results (via the 'results' field, please see below). Each test result must specify the test case ID and can pass in the same fields as add_result, namely all test related system and custom fields.

The difference to add_results is that this method expects test case IDs instead of test IDs. Please see add_result_for_case for details.

Please note that all referenced tests must belong to the same test run.

Request example

The following listing shows a typical example request. In addition to the test case, you need to specify at least one of the status, comment or assignee fields for each result.

{
	"results": [
		{
			"case_id": 1,
			"status_id": 5,
			"comment": "This test failed",
			"defects": "TR-7"

		},
		{
			"case_id": 2,
			"status_id": 1,
			"comment": "This test passed",
			"elapsed": "5m",
			"version": "1.0 RC1"
		},

		..

		{
			"case_id": 1,
			"assignedto_id": 5,
			"comment": "Assigned this test to Joe"
		}

		..
	]
}

Response content

If successful, this method returns the new test results using the same response format as get_results and in the same order as the list of the request.

Response codes

200 Success, the test results were created and are returned as part of the response
400 Invalid or unknown test run/cases
403 No permissions to add test results or no access to the project