API: Plans

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

get_plan

Returns an existing test plan.

GET index.php?/api/v2/get_plan/:plan_id

:plan_id The ID of the test plan

Response content

Please see the following example for a typical response:

{
	"assignedto_id": null,
	"blocked_count": 2,
	"completed_on": null,
	"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,
	"entries": [
	{
		"id": "3933d74b-4282-4c1f-be62-a641ab427063",
		"name": "File Formats",
		"runs": [
		{
			"assignedto_id": 6,
			"blocked_count": 0,
			"completed_on": null,
			"config": "Firefox, Ubuntu 12",
			"config_ids": [
				2,
				6
			],
			"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,
			"entry_id": "3933d74b-4282-4c1f-be62-a641ab427063",
			"entry_index": 1,
			"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"
		},
		{
			..
		}
		],
		"suite_id": 4
	}
	],
	"failed_count": 2,
	"id": 80,
	"is_completed": false,
	"milestone_id": 7,
	"name": "System test",
	"passed_count": 5,
	"project_id": 1,
	"retest_count": 1,
	"untested_count": 6,
	"url": "http://<server>/testrail/index.php?/plans/view/80"
}

The following fields are included in the response:

Name Type Description
assignedto_id int The ID of the user the entire test plan is assigned to
blocked_count int The amount of tests in the test plan marked as blocked
completed_on timestamp The date/time when the test plan was closed (as UNIX timestamp)
created_by int The ID of the user who created the test plan
created_on timestamp The date/time when the test plan was created (as UNIX timestamp)
custom_status?_count int The amount of tests in the test plan with the respective custom status
description string The description of the test plan
entries array An array of 'entries', i.e. group of test runs
failed_count int The amount of tests in the test plan marked as failed
id int The unique ID of the test plan
is_completed bool True if the test plan was closed and false otherwise
milestone_id int The ID of the milestone this test plan belongs to
name string The name of the test plan
passed_count int The amount of tests in the test plan marked as passed
project_id int The ID of the project this test plan belongs to
retest_count int The amount of tests in the test plan marked as retest
untested_count int The amount of tests in the test plan marked as untested
url string The address/URL of the test plan in the user interface

The entries field includes an array of test plan entries. A test plan entry is a group of test runs that belong to the same test suite (just like in the user interface). Each group can have a variable amount of test runs and also supports configurations. Please also see add_plan and add_plan_entry.

Response codes

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

get_plans

Returns a list of test plans for a project.

GET index.php?/api/v2/get_plans/: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 plans created after this date (as UNIX timestamp).
:created_before timestamp Only return test plans 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 plans only. 0 to return active test plans only.
:limit/:offset int Limit the result to :limit test plans. Use :offset to skip records.
:milestone_id int (list) A comma-separated list of milestone IDs to filter by.

# All active test plans for project with ID 1 and milestone 2 or 3
GET index.php?/api/v2/get_plans/1&is_completed=0&milestone_id=2,3

Response content

The response includes an array of test plans. Each test plan in this list follows the same format as get_plan, except for the entries field which is not included in the response.

[
	{ "id": 1, "name": "System test 1", .. },
	{ "id": 2, "name": "System test 2", .. },
	..
]

Response codes

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

add_plan

Creates a new test plan.

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

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

Request fields

The following POST fields are supported:

Name Type Description
name string The name of the test plan (required)
description string The description of the test plan
milestone_id int The ID of the milestone to link to the test plan
entries array An array of objects describing the test runs of the plan, see the example below and add_plan_entry

Request example

The following example shows how to create a new test plan with several test runs:

{
	"name": "System test",
	"entries": [
		{ 
			"suite_id": 1,
			"name": "Custom run name",
			"assignedto_id": 1 // ID of the assignee
		},
		{ 
			"suite_id": 1,
			"include_all": false, // Custom selection
			"case_ids": [1,2,3,5]
		}
	]
}

Starting with TestRail 3.1, add_plan also supports configurations:

{
	"name": "System test",
	"entries": [
		{
			"suite_id": 1,
			"include_all": true,
			"config_ids": [1, 2, 4, 5, 6],
			"runs": [
				{
					"include_all": false,
					"case_ids": [1, 2, 3],
					"assignedto_id": 1,
					"config_ids": [2, 5]
				},
				{
					"include_all": false,
					"case_ids": [1, 2, 3, 5, 8],
					"assignedto_id": 2,
					"config_ids": [2, 6]
				}

				..
			]
		},

		..
	]
}

This will effectively create several test runs per test plan entry, similar to how you can manage test plans and configurations with TestRail's user interface. Please refer to add_plan_entry below for additional details.

Response content

If successful, this method returns the new test plan using the same response format as get_plan.

Response codes

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

add_plan_entry

Adds one or more new test runs to a test plan.

POST index.php?/api/v2/add_plan_entry/:plan_id

:plan_id The ID of the plan the test runs 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(s) (required)
name string The name of the test run(s)
description string The description of the test run(s) (requires TestRail 5.2 or later)
assignedto_id int The ID of the user the test run(s) 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
config_ids array An array of configuration IDs used for the test runs of the test plan entry (requires TestRail 3.1 or later)
runs array An array of test runs with configurations, please see the example below for details (requires TestRail 3.1 or later)

Request example

Also see the following example which shows how to create a new test plan entry with multiple test runs and configurations:

{
	"suite_id": 1,
	"assignedto_id": 1,           // Default assignee
	"include_all": true,          // Default selection
	"config_ids": [1, 2, 4, 5, 6],
	"runs": [
		{
			"include_all": false, // Override selection
			"case_ids": [1, 2, 3],
			"config_ids": [2, 5]
		},
		{
			"include_all": false, // Override selection
			"case_ids": [1, 2, 3, 5, 8],
			"assignedto_id": 2,   // Override assignee
			"config_ids": [2, 6]
		}

		..
	]
}

This will effectively create a new test run for each array element of the runs field. The top-level assignedto_id, include_all and case_ids fields specify the default assignee and test case selection for all test runs. You can override these fields for each test run as demonstrated in the example above.

The top-level config_ids field specifies the combined list of configurations for the list of test runs. All configurations referenced by the individual test runs must be included in this field. Each test run can specify one configuration per included configuration group and needs to match a full configuration combination. For example, let's assume we have the following configurations and configuration groups:

ID Group Configuration
1 Browsers Chrome
2 Browsers Firefox
3 Browsers Internet Explorer
4 Operating Systems Windows 7
5 Operating Systems Windows 8
6 Operating Systems Ubuntu 12

The top-level config_ids field from the example includes the configurations 1, 2, 4, 5 and 6. Valid configuration combinations need to include one configuration from each configuration group. Valid combinations are therefore:

ID Combination
1,4 Chrome, Windows 7
1,5 Chrome, Windows 8
1,6 Chrome, Ubuntu 12
2,4 Firefox, Windows 7
2,5 Firefox, Windows 8
2,6 Firefox, Ubuntu 12

The example chooses to include only two of these combinations, namely 2,5 (Firefox, Windows 8) and 2,6 (Firefox, Ubuntu 12). TestRail in turn will add two separate test runs, one for each combination.

Response content

If successful, this method returns the new test plan entry including test runs using the same response format as the entries field of get_plan, but for a single entry instead of a list of entries.

Response codes

200 Success, the test run(s) were created and are returned as part of the response. Please note that test runs in a plan are organized into 'entries' and these have their own IDs (to be used with update_plan_entry and delete_plan_entry, respectively).
400 Invalid or unknown test plan
403 No permissions to modify test plans or no access to the project

update_plan

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

POST index.php?/api/v2/update_plan/:plan_id

:plan_id The ID of the test plan

With the exception of the entries field, this method supports the same POST fields as add_plan.

Response content

If successful, this method returns the updated test plan using the same response format as get_plan.

Response codes

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

update_plan_entry

Updates one or more existing test runs in a plan (partial updates are supported, i.e. you can submit and update specific fields only).

POST index.php?/api/v2/update_plan_entry/:plan_id/:entry_id

:plan_id The ID of the test plan
:entry_id The ID of the test plan entry (note: not the test run ID)

Request fields

The following POST fields are supported:

Name Type Description
name string The name of the test run(s)
description string The description of the test run(s) (requires TestRail 5.2 or later)
assignedto_id int The ID of the user the test run(s) 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

Response content

If successful, this method returns the updated test plan entry including test runs using the same response format as the entries field of get_plan, but for a single entry instead of a list of entries.

Response codes

200 Success, the test run(s) were updated and are returned as part of the response
400 Invalid or unknown test plan or entry
403 No permissions to modify test plans or no access to the project

close_plan

Closes an existing test plan and archives its test runs & results.

POST index.php?/api/v2/close_plan/:plan_id

:plan_id The ID of the test plan

Please note: Closing a test plan cannot be undone.

Response content

If successful, this method returns the closed test plan using the same response format as get_plan.

Response codes

200 Success, the test plan and all its test runs were closed (archived). The test plan and its test runs are returned as part of the response.
400 Invalid or unknown test plan
403 No permissions to close test plans or no access to the project

delete_plan

Deletes an existing test plan.

POST index.php?/api/v2/delete_plan/:plan_id

:plan_id The ID of the test plan

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

Response codes

200 Success, the test plan and all its test run were deleted
400 Invalid or unknown test plan
403 No permissions to delete test plans or no access to the project

delete_plan_entry

Deletes one or more existing test runs from a plan.

POST index.php?/api/v2/delete_plan_entry/:plan_id/:entry_id

:plan_id The ID of the test plan
:entry_id The ID of the test plan entry (note: not the test run ID)

Please note: Deleting a test run from a plan cannot be undone and also permanently deletes all related test results.

Response codes

200 Success, the test run(s) were removed from the test plan
400 Invalid or unknown test plan or entry
403 No permissions to modify test plans or no access to the project