Runs

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(list) 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)

 

Was this article helpful?
1 out of 1 found this helpful