API: Results - TestRail

API: Results

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

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_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
    :limit Number that sets the limit of test results to be shown on the response (Optional parameter. The response size limit is 250 by default) (requires TestRail 6.7 or later)
    :offset Number that sets the position where the response should start from (Optional parameter)(requires TestRail 6.7 or later)

    This method will return up to 250 entries in the response array. To retrieve additional entries, you can make additional requests using the offset filter described in the Request filters section below.

    Request filters

    The following filters can be applied:

    Name Type Description
    :defects_filter string A single Defect ID (e.g. TR-1, 4291, etc.)
    :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"
	},
	..
] 

    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

    Please see below for a typical response:

    {"offset": 0,
"limit": 250,
"size": 250,
"_links": {
   "next": "/api/v2/get_results/131071&limit=250&offset=250",
   "prev": null},
"results": [
	{
		"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 will return up to 250 entries in the response array. To retrieve additional entries, you can make additional requests using the offset filter described in the Request filters section below.

    Request filters

    The following filters can be applied: 

    Name Type Description
    :defects_filter string A single Defect ID (e.g. TR-1, 4291, etc.)
    :limit integer The number of test results the response should return (The response size is 250 by default) (requires TestRail 6.7 or later)
    :offset integer Where to start counting the tests results from (the offset) (requires TestRail 6.7 or later)
    :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 Content 

    This method uses the same response format as get_results.

    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.

    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.

    GET index.php?/api/v2/get_results_for_run/:run_id
    :run_id The ID of the test run

    This method will return up to 250 entries in the response array. To retrieve additional entries, you can make additional requests using the offset filter described in the Request filters section below.

    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.
    :defects_filter string A single Defect ID (e.g. TR-1, 4291, etc.)
    :limit int Number that sets the limit of results 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)
    :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 Content 

    This method uses the same response format as get_results.

    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.

    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.

    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.

    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