API: Runs

Use the following API methods to request details about test runs and to create or modify test runs.

get_run

Returns an existing test run. Please see get_tests for the list of included tests in this run.

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

:run_id The ID of the test run

Response content

Please see below for a typical response:

{
	"assignedto_id": 6,
	"blocked_count": 0,
	"completed_on": null,
	"config": "Firefox, Ubuntu 12",
	"config_ids": [
		2,
		6
	],
	"created_by": 1,
	"created_on": 1393845644,
	"custom_status1_count": 0,
	"custom_status2_count": 0,
	"custom_status3_count": 0,
	"custom_status4_count": 0,
	"custom_status5_count": 0,
	"custom_status6_count": 0,
	"custom_status7_count": 0,
	"description": null,
	"failed_count": 2,
	"id": 81,
	"include_all": false,
	"is_completed": false,
	"milestone_id": 7,
	"name": "File Formats",
	"passed_count": 2,
	"plan_id": 80,
	"project_id": 1,
	"retest_count": 1,
	"suite_id": 4,
	"untested_count": 3,
	"url": "http://<server>/testrail/index.php?/runs/view/81"
}

The following fields are included in the response:

Name Type Description
assignedto_id int The ID of the user the entire test run is assigned to
blocked_count int The amount of tests in the test run marked as blocked
completed_on timestamp The date/time when the test run was closed (as UNIX timestamp)
config string The configuration of the test run as string (if part of a test plan)
config_ids array The array of IDs of the configurations of the test run (if part of a test plan)
created_by int The ID of the user who created the test run
created_on timestamp The date/time when the test run was created (as UNIX timestamp)
custom_status?_count int The amount of tests in the test run with the respective custom status
description string The description of the test run
failed_count int The amount of tests in the test run marked as failed
id int The unique ID of the test run
include_all bool True if the test run includes all test cases and false otherwise
is_completed bool True if the test run was closed and false otherwise
milestone_id int The ID of the milestone this test run belongs to
plan_id int The ID of the test plan this test run belongs to
name string The name of the test run
passed_count int The amount of tests in the test run marked as passed
project_id int The ID of the project this test run belongs to
retest_count int The amount of tests in the test run marked as retest
suite_id int The ID of the test suite this test run is derived from
untested_count int The amount of tests in the test run marked as untested
url string The address/URL of the test run in the user interface

Response codes

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

get_runs

Returns a list of test runs for a project. Only returns those test runs that are not part of a test plan (please see get_plans/get_plan for this).

GET index.php?/api/v2/get_runs/:project_id

:project_id The ID of the project

Request filters

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

Name Type Description
:created_after timestamp Only return test runs created after this date (as UNIX timestamp).
:created_before timestamp Only return test runs created before this date (as UNIX timestamp).
:created_by int (list) A comma-separated list of creators (user IDs) to filter by.
:is_completed bool 1 to return completed test runs only. 0 to return active test runs only.
:limit/:offset int Limit the result to :limit test runs. Use :offset to skip records.
:milestone_id int (list) A comma-separated list of milestone IDs to filter by.
:suite_id int (list) A comma-separated list of test suite IDs to filter by.

# All active test runs for project with ID 1 created by user with ID 1 or 2
GET index.php?/api/v2/get_runs/1&is_completed=0&created_by=1,2

Response content

The response includes an array of test runs. Each test run in this list follows the same format as get_run.

[
	{ "id": 1, "name": "Test run 1", .. },
	{ "id": 2, "name": "Test run 2", .. },
	..
]

Response codes

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

add_run

Creates a new test run.

POST index.php?/api/v2/add_run/:project_id

:project_id The ID of the project the test run should be added to

Request fields

The following POST fields are supported:

Name Type Description
suite_id int The ID of the test suite for the test run (optional if the project is operating in single suite mode, required otherwise)
name string The name of the test run
description string The description of the test run
milestone_id int The ID of the milestone to link to the test run
assignedto_id int The ID of the user the test run should be assigned to
include_all bool True for including all test cases of the test suite and false for a custom case selection (default: true)
case_ids array An array of case IDs for the custom case selection

Request example

Also see the following example which shows how to create a new test run including a custom test case selection:

{
	"suite_id": 1,
	"name": "This is a new test run",
	"assignedto_id": 5,
	"include_all": false,
	"case_ids": [1, 2, 3, 4, 7, 8]
}

Response content

If successful, this method returns the new test run using the same response format as get_run.

Response codes

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

update_run

Updates an existing test run (partial updates are supported, i.e. you can submit and update specific fields only).

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

:run_id The ID of the test run

With the exception of the suite_id and assignedto_id fields, this method supports the same POST fields as add_run.

Request example

Also see the following example which shows how to update the description and test case selection of a test run:

{
	"description": "A description for the test run",
	"include_all": true
}

The following example updates a test run to use a manual test case selection:

{
	"include_all": false,
	"case_ids": [1, 2, 3, 5, 8]
}

Response content

If successful, this method returns the updated test run using the same response format as get_run.

Response codes

200 Success, the test run was updated and is returned as part of the response
400 Invalid or unknown test run
403 No permissions to modify test runs or no access to the project

close_run

Closes an existing test run and archives its tests & results.

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

:run_id The ID of the test run

Please note: Closing a test run cannot be undone.

Response content

If successful, this method returns the closed test run using the same response format as get_run.

Response codes

200 Success, the test run was closed (archived) and is returned as part of the response.
400 Invalid or unknown test run
403 No permissions to close test runs or no access to the project

delete_run

Deletes an existing test run.

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

:run_id The ID of the test run

Please note: Deleting a test run cannot be undone and also permanently deletes all tests & results of the test run.

Response codes

200 Success, the test run and all its tests & results were deleted
400 Invalid or unknown test run
403 No permissions to delete test runs or no access to the project