API: Plans - TestRail

API: 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.

On this page:

    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:

    {
    	"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",
    		""description": null,"
    		""include_all": true,"
    		"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,
    			"refs": "RF-1, RF-2"
    			"suite_id": 4,
    			"untested_count": 3,
    			"url": "http:///testrail/index.php?/runs/view/81"
    		},
    		{
    			..
    		}
    		],
    		"refs": "RF-1, RF-2"
    		"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:///testrail/index.php?/plans/view/80"
    }
    

    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 In Description
    project_id
    integer true path The ID of the project
    created_after
    timestamp false query Only return test plans created after this date (as UNIX timestamp).
    created_before
    timestamp false query Only return test plans created before this date (as UNIX timestamp).
    created_by
    integer (list) false query A comma-separated list of creators (user IDs) to filter by.
    is_completed
    boolean false query 1 to return completed test plans only. 0 to return active test plans only.
    limit/offset
    integer false query Limit the result to :limit test plans. Use :offset to skip records.
    milestone_id
    integer (list) false query 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

    Response 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 run(s)—requires TestRail 5.2 or later
    assignedto_id
    integer false The ID of the user the test run(s) 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
    config_ids
    array false An array of configuration IDs used for the test runs of the test plan entry
    refs
    string false A string of external requirement IDs, separated by commas—requires TestRail 6.3 or later
    runs
    array false An array of test runs with configurations, please see the example below for details

    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

    Adds a new test run to a test plan entry (using configurations).

    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)
    name
    string false 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(s) 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 
    refs
    string false A string of external requirement IDs, separated by commas. - requires TestRail 6.3 or later

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

    Response codes

    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 which uses configurations

    Requires TestRail 6.4 or later

    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
    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 See description 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 update a run inside a plan entry which 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

    info 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

    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

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

    Response codes

    Status Code Description
    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
    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
    integer true The ID of the test plan entry (note: not the test run ID)

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

    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)