Runs

Updated November 10, 2023 22:03

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}

Parameters

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

Example request:

# Get the test run with an ID of 42
GET index.php?/api/v2/get_run/42

Response content

Example response:

{
    "assignedto_id": 6,
    "blocked_count": 0,
    "completed_on": null,
    "config": "Firefox, Ubuntu 12",
    "config_ids": [
        2,
        6
    ],
    "created_by": 1,
    "created_on": 1393845644,
    "refs": "SAN-1",
    "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,
    "updated_on": null,
    "url": "http://{server}/testrail/index.php?/runs/view/81"
}

The following system fields are always included in the response:

Name	Type	Description
assignedto_id	integer	The ID of the user the entire test run is assigned to
blocked_count	integer	The number 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 a 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	integer	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	integer	The number of tests in the test run with the respective custom status
description	string	The description of the test run
failed_count	integer	The number of tests in the test run marked as failed
id	integer	The unique ID of the test run
include_all	boolean	True if the test run includes all test cases and false otherwise
is_completed	boolean	True if the test run was closed and false otherwise
milestone_id	integer	The ID of the milestone this test run belongs to
plan_id	integer	The ID of the test plan this test run belongs to
name	string	The name of the test run
passed_count	integer	The number of tests in the test run marked as passed
project_id	integer	The ID of the project this test run belongs to
retest_count	integer	The number of tests in the test run marked as retest
suite_id	integer	The ID of the test suite this test run is derived from
untested_count	integer	The number of tests in the test run marked as untested
updated_on	timestamp	The date/time when the test run was updated — requires TestRail 6.5.2 or later.
url	string	The address/URL of the test run in the user interface
refs	string	A comma-separated list of references/requirements

Response codes

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

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}

Parameters

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

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.

Request filters

The following filters can be applied using query parameters in the request URL:

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	integer	A comma-separated list of creators (user IDs) to filter by
is_completed	boolean	1 to return completed test runs only. 0 to return active test runs only
limit/offset	integer	Limit the result to limit test runs. Use offset to skip records
milestone_id	integer(list)	A comma-separated list of milestone IDs to filter by
refs_filter	string	A single Reference ID (e.g. TR-a, 4291, etc.)
suite_id	integer(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 the ‘runs’ array follows the same format as get_run.

{
    "offset": 0,
    "limit": 250,
    "size": 250,
    "_links": {
        "next": "/api/v2/get_cases/1&limit=250&offset=250",
        "prev": null
    },
    "runs": [
        {
            "id": 1,
            "name": "Test run 1",
        },
        {
            "id": 2,
            "name": "Test run 2",
        },
    ]
}

Response codes

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

add_run

Creates a new test run.

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

Parameters

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

Request body

The following filters can be applied in the body message of the request:

Name	Type	Description
suite_id	integer	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	integer	The ID of the milestone to link to the test run
assignedto_id	integer	1 to return completed test runs only. 0 to return active test runs onlyThe ID of the user the test run should be assigned to
include_all	boolean	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
refs	string	A comma-separated list of references/requirements — requires TestRail 6.1 or later

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,
    "refs": "SAN-1, SAN-2",
    "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

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

update_run

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

To update test runs inside test plans, please see API:plans.

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

Parameters

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

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

close_run

Closing a test run cannot be undone.

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

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

Parameters

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

Response content

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

Response codes

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

delete_run

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

Deletes an existing test run.

To delete a test run within a test plan, please see API:Plans.

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

Parameters

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

Soft Parameter

Omitting the soft parameter, or submitting soft=0 will delete the test run and its tests.

If soft=1, this will return data on the number of affected tests.

Including soft=1 will not actually delete the entity.

Response codes

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