Plans

Use the following API methods to request details about test plans and to create or modify test plans. In TestRail, test plans allow you to group multiple test runs together and automatically generate test runs for various browser, OS, or other configurations you set without having to add each test run individually.

get_plan

 Returns an existing test plan.

GET index.php?/api/v2/get_plan/{plan_id}

Parameters

Name	Type	Required	Description
plan_id	integer	true	The ID of the test plan

Response content

Example response:

{
    "id": 10,
    "name": "Release 1.0: Final (all browsers)",
    "description": null,
    "milestone_id": 3,
    "assignedto_id": null,
    "is_completed": false,
    "completed_on": null,
    "passed_count": 445,
    "blocked_count": 99,
    "untested_count": 473,
    "retest_count": 107,
    "failed_count": 56,
    "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,
    "project_id": 1,
    "created_on": 1646058671,
    "created_by": 1,
    "url": "https://74trialapitesting.testrail.io/index.php?/plans/view/10",
    "entries": [
        {
            "id": "75698796-61d5-46e8-9c14-d334351f12d0",
            "suite_id": 1,
            "name": "Browser test",
            "refs": null,
            "description": null,
            "include_all": true,
            "runs": [
                {
                    "id": 13,
                    "suite_id": 1,
                    "name": "Browser test",
                    "description": null,
                    "milestone_id": 3,
                    "assignedto_id": null,
                    "include_all": true,
                    "is_completed": false,
                    "completed_on": null,
                    "passed_count": 88,
                    "blocked_count": 20,
                    "untested_count": 97,
                    "retest_count": 19,
                    "failed_count": 12,
                    "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,
                    "project_id": 1,
                    "plan_id": 10,
                    "entry_index": 1,
                    "entry_id": "75698796-61d5-46e8-9c14-d334351f12d0",
                    "config": "Chrome",
                    "config_ids": [
                        3
                    ],
                    "created_on": 1646058671,
                    "refs": null,
                    "created_by": 1,
                    "url": "https://74trialapitesting.testrail.io/index.php?/runs/view/13"
                }
            ]
        }
    ]
}

The following fields are included in the response:

Name	Type	Description
assignedto_id	integer	The ID of the user the entire test plan is assigned to
blocked_count	integer	The number 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	integer	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	integer	The number 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	integer	The number of tests in the test plan marked as failed
id	integer	The unique ID of the test plan
is_completed	boolean	True if the test plan was closed and false otherwise
milestone_id	integer	The ID of the milestone this test plan belongs to
name	string	The name of the test plan
passed_count	integer	The number of tests in the test plan marked as passed
project_id	integer	The ID of the project this test plan belongs to
refs	string	A string of external requirement IDs, separated by commas - requires TestRail 6.3 or later
retest_count	integer	The number of tests in the test plan marked as a retest
untested_count	integer	The number 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

Status Code	Description
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
429	TestRail Cloud only—Too many requests (see API rate limit)

get_plans

Returns a list of test plans for a project.

GET index.php?/api/v2/get_plans/{project_id}

Parameters

Name	Type	Required	Description
project_id	integer	true	The ID of the project

Request body

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

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.

# 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.

{
    "offset": 0,
    "limit": 250,
    "size": 1,
    "_links": {
        "next": null,
        "prev": null,
    },
    "plans": [
        {
            "id": 1,
            "name": "System test 1", 
            // ..
        },
        {
            "id": 2,
            "name": "System test 2", 
            // ..
        },
        // ..
    ]
}

Response codes

Status Code	Description
200	Success (the test plans are returned as part of the response)
400	Invalid or unknown test plan
403	No access to the project
429	TestRail Cloud only—Too many requests (see API rate limit)

add_plan

Creates a new test plan.

POST index.php?/api/v2/add_plan/{project_id}

Parameters

Name	Type	Required	Description
project_id	integer	true	The ID of the project the test plan should be added to

Request body

Name	Type	Required	Description
name	string	true	The name of the test plan
description	string	false	The description of the test plan
milestone_id	integer	false	The ID of the milestone to link to the test plan
entries	array	false	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]
        }
    ]
}

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.

The 'refs' field is supported with TestRail 6.3 or later.

Response content

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

Response codes

Status Code	Description
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
429	TestRail Cloud only—Too many requests (see API rate limit)

add_plan_entry

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

POST index.php?/api/v2/add_plan_entry/{plan_id}

Parameters

Name	Type	Required	Description
plan_id	integer	true	The ID of the plan the test runs should be added to

Request body

Name	Type	Required	Description
suite_id	integer	See description	The ID of the test suite for the test run(s) (required if using a projects with multiple suite or baseline support)
name	string	false	The name of the test run(s)
description	string	false	The description of the test plan
assignedto_id	integer	false	1 to return completed test plans only. 0 to return active test plans only
include_all	boolean	false	Limit the result to :limit test plans. Use :offset to skip records
case_ids	array	false	An array of case IDs for the custom case selection (Required if include_all is false)
config_ids	array	false	An array of configuration IDs used for the test run of the test plan entry
refs	string	false	A comma-separated list of references/requirements
runs	array	false	An array of test runs

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

Status Code	Description
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
429	TestRail Cloud only—Too many requests (see API rate limit)

add_run_to_plan_entry

POST index.php?/api/v2/add_run_to_plan_entry/{plan_id}/{entry_id}

Parameters

Name	Type	Required	Description
plan_id	integer	true	The ID of the plan the test runs should be added to
entry_id	string	true	The ID of the test plan entry

Request body

Name	Type	Required	Description
config_ids	array	true	An array of configuration IDs used for the test run of the test plan entry
description	text	false	The description of the test run
assignedto_id	integer	false	The ID of the user the test run should be assigned to
include_all	boolean	false	True for including all test cases of the test suite and false for a custom case selection
case_ids	array	false	An array of case IDs for the custom case selection (Required if include_all is false)
refs	string	false	A comma-separated list of references/requirements

Request example

Also, see the following example which shows how to add a new test run to a test plan entry:

{
    "config_ids": [1, 5],
    "include_all": false,
    "case_ids": [1, 2, 4]
}

Response codes

Status Code	Description
200	Success (the test run was updated and is returned as part of the response)
400	Invalid or unknown test plan or plan entry, or invalid POST body
403	No permissions to modify test plans or no access to the project
429	TestRail Cloud only—Too many requests (see API rate limit)

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}

Parameters

Name	Type	Required	Description
plan_id	integer	true	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

Status Code	Description
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
429	TestRail Cloud only—Too many requests (see API rate limit)

update_plan_entry

Updates one or more groups of 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}

Parameters

Name	Type	Required	Description
plan_id	integer	true	The ID of the test plan
entry_id	string	true	The ID of the test plan entry (note: not the test run ID)

Request body

Name	Type	Required	Description
name	string	true	The name of the test run(s)
description	text	false	The description of the test run(s) - requires TestRail 5.2 or later
assignedto_id	integer	false	The ID of the user the test run should be assigned to
include_all	boolean	false	True for including all test cases of the test suite and false for a custom case selection (default: true)
case_ids	array	false	An array of case IDs for the custom case selection (Required if include_all is false)
refs	string	false	A string of external requirement IDs, separated by commas. - requires TestRail 6.3 or later

 

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

Status Code	Description
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
429	TestRail Cloud only—Too many requests (see API rate limit)

update_run_in_plan_entry

Updates a run inside a plan entry that uses configurations.

POST index.php?/api/v2/update_run_in_plan_entry/{run_id}

Parameters

Name	Type	Required	Description
run_id	integer	true	The ID of the test run

Request body

Name	Type	Required	Description
description	text	false	The description of the test run
assignedto_id	integer	false	The ID of the user the test run should be assigned to
include_all	boolean	false	True for including all test cases of the test suite and false for a custom case selection (default: true)
case_ids	array	See description	An array of case IDs for the custom case selection (Required if include_all is false)
refs	string	false	A string of external requirement IDs, separated by commas. - requires TestRail 6.3 or later

Request example

Also, see the following example which shows how to update a run inside a plan entry that uses configurations:

{
    "include_all": false,
    "case_ids": [1,2,4]
}

Response codes

Status Code	Description
200	Success (the test run was updated and is returned as part of the response)
400	Invalid or unknown test run or invalid POST body
403	No permissions to modify test plans or no access to the project
429	TestRail Cloud only—Too many requests (see API rate limit)

close_plan

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

POST index.php?/api/v2/close_plan/{plan_id}

Parameters

Name	Type	Required	Description
plan_id	integer	true	The ID of the test plan

Response content

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

Response codes

Status Code	Description
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
429	TestRail Cloud only—Too many requests (see API rate limit)

delete_plan

Deletes an existing test plan.

POST index.php?/api/v2/delete_plan/{plan_id}

Parameters

Name	Type	Required	Description
plan_id	integer	true	The ID of the test plan

Response codes

Status Code	Description
200	Success (the test plan and all its test runs were deleted)
400	Invalid or unknown test plan
403	No permissions to delete test plans or no access to the project
429	TestRail Cloud only—Too many requests (see API rate limit)

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}

Parameters

Name	Type	Required	Description
plan_id	integer	true	The ID of the test plan
entry_id	string	true	The ID of the test plan entry (note: not the test run ID)

Response codes

Status Code	Description
200	Success (the test run(s) were removed from the test plan)
400	Invalid or unknown test plan or entry
403	No permissions to delete test plans or no access to the project
429	TestRail Cloud only—Too many requests (see API rate limit)

delete_run_from_plan_entry

Deletes a test run from a test plan entry

POST index.php?/api/v2/delete_run_from_plan_entry/{run_id}

Parameters

Name	Type	Required	Description
run_id	integer	true	The ID of the test run

Response codes

Status Code	Description
200	Success (the test run(s) were removed from the test plan)
400	Invalid or unknown test plan or entry
403	No permissions to delete test plans or no access to the project
429	TestRail Cloud only—Too many requests (see API rate limit)