Suites

Updated September 15, 2026 12:33

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

get_suite

Returns an existing test suite.

GET index.php?/api/v2/get_suite/{suite_id}

Parameters

Name	Type	Required	Description
suite_id	integer	true	The ID of the test suite

get_suite returns one test suite and does not support pagination.

Response content

Please see below for a typical example response:

{
  "completed_on": null,
  "description": "Tests covering installation and initial setup.",
  "id": 1,
  "is_baseline": false,
  "is_completed": false,
  "is_master": false,
  "name": "Setup & Installation",
  "project_id": 1,
  "url": "https://example.testrail.io/index.php?/suites/view/1"
}

The following fields are included in the response:

Name	Type	Description
completed_on	timestamp	The date/time when the test suite was closed (as UNIX timestamp) (added with TestRail 4.0)
description	string	The description of the test suite
id	integer	The unique ID of the test suite
is_baseline	boolean	True if the test suite is a baseline test suite and false otherwise (added with TestRail 4.0)
is_completed	boolean	True if the test suite is marked as completed/archived and false otherwise (added with TestRail 4.0)
is_master	boolean	True if the test suite is a master test suite and false otherwise (added with TestRail 4.0)
limit/offset	integer	Limit the result to limit test suites. Use offset to skip records
name	string	The name of the test suite
project_id	integer	The ID of the project this test suite belongs to
url	string	The address/URL of the test suite in the user interface

Response codes

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

get_suites

Returns a paginated list of test suites for a project.

GET index.php?/api/v2/get_suites/{project_id}

Parameters

Name	Type	Required	Description
project_id	integer	true	The ID of the project
limit	integer	no	The maximum number of suites to return in one response. The default and maximum value is 250; values from 1 through 250 can be specified. (Requires TestRail 9.3.1 or later)
offset	integer	no	The number of suites to skip before returning results. The default is 0. Use this parameter to request subsequent pages. (Requires TestRail 9.3.1 or later)

Pagination parameters are appended to the request URL with &. For example, the following request returns up to 100 suites beginning with the 101st suite:

GET index.php?/api/v2/get_suites/1&limit=100&offset=100

To retrieve every suite, follow the URL in _links.next until next is null. Alternatively, increase offset by limit for each request. TestRail documents the default page size and maximum limit as 250.

Response content

The response is a pagination object containing a suites array. Each object in suites follows the same format as the response from get_suite.

{
  "offset": 0,
  "limit": 2,
  "size": 2,
  "_links": {
    "next": "/api/v2/get_suites/1&limit=2&offset=2",
    "prev": null
  },
  "suites": [
    {
      "completed_on": null,
      "description": "Tests covering installation and initial setup.",
      "id": 1,
      "is_baseline": false,
      "is_completed": false,
      "is_master": false,
      "name": "Setup & Installation",
      "project_id": 1,
      "url": "https://example.testrail.io/index.php?/suites/view/1"
    },
    {
      "completed_on": null,
      "description": "Tests covering document-editing features.",
      "id": 2,
      "is_baseline": false,
      "is_completed": false,
      "is_master": false,
      "name": "Document Editing",
      "project_id": 1,
      "url": "https://example.testrail.io/index.php?/suites/view/2"
    }
  ]
}

The top-level response fields are:

GET index.php?/api/v2/get_suites/{project_id}

Name	Type	Description
offset	integer	The offset used for the current page.
limit	integer	The maximum number of suites requested for the current page.
size	integer	The number of suites included in the current response.
_links	object	Links used to navigate between pages.
_links.next	string or null	The relative URL for the next page. Returns null when there are no more suites.
_links.prev	string or null	The relative URL for the previous page. Returns null on the first page.
suites	array	The test suites returned for the current page. Each entry follows the get_suite response format.

For example, the request for the next page from the response above would be:

GET index.php?/api/v2/get_suites/1&limit=2&offset=2

If that page contains the final suite, the response would resemble:

{
  "offset": 2,
  "limit": 2,
  "size": 1,
  "_links": {
    "next": null,
    "prev": "/api/v2/get_suites/1&limit=2&offset=0"
  },
  "suites": [
    {
      "completed_on": null,
      "description": "Tests covering import and export workflows.",
      "id": 3,
      "is_baseline": false,
      "is_completed": false,
      "is_master": false,
      "name": "Import and Export",
      "project_id": 1,
      "url": "https://example.testrail.io/index.php?/suites/view/3"
    }
  ]
}

Response codes

Status Code	Description
200	Success (the test suites are 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)

Behavior before TestRail 9.3.1

Pagination was introduced for get_suites in TestRail 9.3.1. In earlier versions, the endpoint did not accept limit or offset, and it returned all accessible suites as a top-level JSON array. The request URL itself did not otherwise change. TestRail identifies the 9.3.1 update as a breaking change because the top-level response changed from an array to a pagination object.

More details on get_suites before 9.3.1

Request before TestRail 9.3.1:

GET index.php?/api/v2/get_suites/1

Example response before TestRail 9.3.1:

[
  {
    "completed_on": null,
    "description": "Tests covering installation and initial setup.",
    "id": 1,
    "is_baseline": false,
    "is_completed": false,
    "is_master": false,
    "name": "Setup & Installation",
    "project_id": 1,
    "url": "https://example.testrail.io/index.php?/suites/view/1"
  },
  {
    "completed_on": null,
    "description": "Tests covering document-editing features.",
    "id": 2,
    "is_baseline": false,
    "is_completed": false,
    "is_master": false,
    "name": "Document Editing",
    "project_id": 1,
    "url": "https://example.testrail.io/index.php?/suites/view/2"
  }
]

From TestRail 9.3.1 onward, the same request returns the first page using the default limit:

GET index.php?/api/v2/get_suites/1

{
  "offset": 0,
  "limit": 250,
  "size": 2,
  "_links": {
    "next": null,
    "prev": null
  },
  "suites": [
    {
      "id": 1,
      "name": "Setup & Installation"
    },
    {
      "id": 2,
      "name": "Document Editing"
    }
  ]
}

add_suite

Creates a new test suite.

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

Parameters

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

Request body

The following fields are supported in the POST request body:

Name	Type	Required	Description
name	string	true	The name of the test suite
description	string	false	The description of the test suite

Request example

Also see the following example which shows how to create a new, empty test suite:

{
    "name": "This is a new test suite",
    "description": "Use the description to add additional context details"
}

Once you’ve added a test suite, you can start adding sections and test cases.

Response content

If successful, this method returns the new test suite using the same response format as get_suite.

Response codes

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

update_suite

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

POST index.php?/api/v2/update_suite/{suite_id}

Parameters

Name	Type	Required	Description
suite_id	integer	true	The ID of the test suite

This method supports the same POST fields as add_suite.

Response content

If successful, this method returns the updated test suite using the same response format as get_suite.

Response codes

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

delete_suite

Deleting a test suite cannot be undone and also deletes all active test runs & results, i.e. test runs & results that weren’t closed (archived) yet.

Deletes an existing test suite.

POST index.php?/api/v2/delete_suite/{suite_id}

Parameters

Name	Type	Required	Description
suite_id	integer	true	The ID of the test suite

Soft Parameter

Omitting the soft parameter, or submitting soft=0 will delete the test suite and its test cases

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

Including soft=1 will not actually delete the entity.

Response codes

Status Code	Description
200	Success (the test suite and all active test runs and results were deleted)
400	Invalid or unknown test suite
403	No permissions to delete test suites or no access to the project
429	TestRail Cloud only—Too many requests (see API rate limit)