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_planexcept 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 A comma-separated list of creators (user IDs) to filter by
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 A comma-separated list of milestone IDs to filter by
config_ids array false A comma-separated list of milestone IDs to filter by
refs string false A comma-separated list of milestone IDs to filter by
runs array false A comma-separated list of milestone IDs to filter by

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_idinclude_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 1245 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

 

This endpoint requires TestRail 6.4 or later.

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 integer 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 integer 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

 

 

The config_ids and runs fields are not supported in POST calls to the update_plan_entry endpoint.

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

 

This endpoint requires TestRail 6.4 or later.

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

 

Closing a test plan cannot be undone.

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

 

Deleting a test plan cannot be undone and also permanently deletes all test runs & results of the test 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

 

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

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 integer 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)
Was this article helpful?
0 out of 0 found this helpful