API: Runs - TestRail

API: Runs

Use the following API methods to request details about test runs and to create or modify test runs.

On this page:

    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:

    Key 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 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
    created_after timestamp false Only return test runs created after this date (as UNIX timestamp)
    created_before timestamp false Only return test runs created before this date (as UNIX timestamp)
    created_by integer false A comma-separated list of creators (user IDs) to filter by
    is_completed boolean false 1 to return completed test runs only. 0 to return active test runs only
    limit/offset integer false Limit the result to limit test runs. Use offset to skip records
    milestone_id integer(list) false A comma-separated list of milestone IDs to filter by
    refs_filter string false A single Reference ID (e.g. TR-a, 4291, etc.)
    suite_id integer(list) false A comma-separated list of test suite 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.

    Request fields

    The following filters can be applied:

    # 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 ‘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
    suite_id integer false The ID of the test suite for the test run (optional if the project is operating in single suite mode, required otherwise)
    name string false The name of the test run
    description string false The description of the test run
    milestone_id integer false The ID of the milestone to link to 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 false An array of case IDs for the custom case selection
    refs
    string false 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 codes

    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

    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

    info Please Note: Closing a test run cannot be undone.

    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

    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

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

    Including soft=1 will not actually delete the entity.

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

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

    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)