Introduction to the TestRail API

TestRail’s API can be used to integrate TestRail with various tools, frameworks and third-party applications. For example, many customers use the API to integrate their automated tests and submit test results to TestRail. The API can be used for various other tasks as well and you can find a small list of examples below.

The API is HTTP-based and can thus be used from virtually any framework, programming language and tool. Submitting data to TestRail via the API is done via simple POST requests. Requesting data is done through GET requests. All requests and responses use the JSON format and UTF-8 encoding.

Some typical scenarios the API can be used for:

• Submit test results from automated tests
• Migrate test cases from legacy systems
• Synchronize test cases between different systems
• Create test runs and plans programmatically
• Query information for integrations

API rate limit

Please note that the API is rate-limited on TestRail Cloud to ensure optimal performance for all users and may throttle requests. TestRail might also return a 429 Too Many Requests response, which you are expected to handle. Such a response also includes a Retry-After header indicating how many seconds to wait before you are allowed to submit the next request.

To avoid rate limits on TestRail Cloud, try using bulk API endpoints (e.g. using as add_results_for_cases instead of add_results_for case), build a time delay into your API calls, or upgrade to TestRail Enterprise Cloud.

Rate limits for TestRail Cloud are as follows:

• 180 Requests per instance, per minute for TestRail Cloud Professional subscriptions.
• 300 Requests per instance, per minute for TestRail Cloud Enterprise subscriptions.

API offset and limit parameters

There are many bulk API endpoints available in TestRail that enable you to retrieve information about multiple cases, tests, or other TestRail entities with a single GET request. This makes it faster and more efficient to retrieve information from TestRail while simplifying the process and reducing the overall number of requests sent to the TestRail API (especially relevant if you are hitting the API rate limit on TestRail Cloud).

Limit

When using a bulk GET endpoint (like get_cases, get_runs, or get_results_for_case) the default number of records that are returned is 250. However, you can use the limit parameter to reduce the number further if desired.

For example, if you’re using the get_runs API method and only wanted to return the first three test runs in a project with project_id of 3, you would send the following request:

GET https://{hostname}/index.php?/api/v2/get_runs/3&limit=3

Please note, you would need to replace {hostname} with the actual URL for your TestRail instance.

The expected response would look like this:

{
  "offset": 0,
  "limit": 3,
  "size": 3,
  "_links": {
    "next": "/api/v2/get_runs/3&limit=3&offset=3",
    "prev": null
  },
  "runs": [
    {
      "id": 1,
      ..
    },
    {
      "id": 2,
      ..
    },
    {
      "id": 3,
      ..
    }
  ]
}

You can specify an integer as low as 1 for the limit parameter and as high as 250, which is the max number of records allowed in the response. If you try a value greater than the 250 limits you’ll receive the following error:

{
  "error": "Field :limit is too large (maximum 250)."
}

Offset

The offset parameter is what is used to navigate to the next set of results. For example, if you are using the get_cases endpoint to retrieve data for all the test cases in your instance and don’t set a separate limit value, your initial request will return a maximum of 250 test cases records since the default maximum number of results is 250.

Example output:

{
  "offset": 0,
  "limit": 250,
  "size": 250,
  "_links": {
    "next": "api/v2/get_cases/3&limit=250&offset=250",
    "prev": null
  },
  "cases": [
    {
      "id": 2604,
      "title": "Add watermark to document and verify print output",
      "section_id": 268,
      "template_id": 1,
      "type_id": 7,
      "priority_id": 4,
      "milestone_id": null,
      "refs": null,
      "created_by": 2,
      "created_on": 1631664168,
      "updated_by": 2,
      "updated_on": 1631664168,
      "estimate": null,
      "estimate_forecast": "8m 40s",
      "suite_id": 32,
      "display_order": 1,
      "is_deleted": 0,
      "custom_automation_type": 0,
      "custom_automation_status": null,
      "custom_preconds": null,
      "custom_steps": null,
      "custom_expected": "Etiam massa dolor, ornare sit amet, lacinia nec, bibendum ut, magna.\n\t\t\n* Nam feugiat, eros at commodo dictum,\n* Felis libero varius orci, in vulputate\n* Massa turpis scelerisque diam.\n* Nunc et felis est. Phasellus laoreet nibh vel augue\n* Faucibus at varius est pretium.\n\nQuisque pellentesque **mauris**.",
      "custom_steps_separated": null,
      "custom_mission": null,
      "custom_goals": null
    },
    ..
  ]
}

If you have more than 250 test cases in your project, you will need to send another GET request to retrieve the next set of records, this time setting the offset parameter to 250, like so:

GET https://{hostname}/index.php?/api/v2/get_cases/3&offset=250

The response would be the next 250 test cases since we’re using the get_cases method in the example above.

Note: Records that can be queried with a bulk GET request are ordered by the ID values of those entities. For example, get_cases will return cases in ascending order of each case’s ID.

To iterate to the next set of records, you can either use the next value in the _links object returned in the previous response, or you can manually iterate over the offset number until you reach the end of the offsets.

You can tell once you’ve reached the end of the number of records available two ways. If your current request contains the final record in whatever table you are querying, the response will return a null value for the next value in the _links object. Additionally, if you enter an offset that is larger than the number of records available, you’ll be presented with an empty array. For example:

GET https://{hostname}/index.php?/api/v2/get_cases/3&offset=10000000

Example output:

{
  "offset": 10000000,
  "limit": 250,
  "size": 0,
  "_links": {
    "next": null,
    "prev": "/api/v2/get_cases/3&offset=9999750&limit=250"
  },
  "cases": []
}

You can use this to determine if you’ve hit the end of the records or not in your automation.

Conventions used in API Reference

The TestRail API manual uses a few conventions to indicate variable parameters that should be replaced in API request URLs and truncate the way some examples of responses are displayed in the documentation.

1. Variables with curly braces

Replace any values with curly braces { } in API requests with actual parameters.

For example, in the API request, GET index.php?/api/v2/get_project/{project_id}, replace {project_id} with the value for your actual project id.

So, if your project id is 10, the request would be GET index.php?/api/v2/get_project/10

2. Truncated response code examples

.. in a code block indicates truncating of the response, which is used purely for aesthetic purposes in the documentation and do not reflect actual response content from the TestRail API. This is used in examples throughout the API reference guide merely to shorten the space responses take in the documentation itself and hopefully make the article more readable.

For example, please see the below example of a response using the get_cases endpoint.

{
  "offset": 0,
  "limit": 250,
  "size": 250,
  "_links":{
    "next": "/api/v2/get_cases/1&limit=250&offset=250",
    "prev": null
  },
  "cases":[
    { "id": 1, "title": "..", .. },
    { "id": 2, "title": "..", .. },
    ..
  ]
}

How to find ID variables for API calls?

Many TestRail API endpoints require you to add an ID value in the request URL to specify certain projects, cases, test runs, and more. In the below section, you will learn where to find specific IDs in TestRail UI and how to use them as a parameter in an API request.

Project ID – project_id

1. Go to the ‘Dashboard’ on your TestRail instance.
2. Select a project from the list.
3. Check the URL. The numeric character you see at the end is the project’s ID, or you can also get the
4. ID next to project name (please make sure to omit the character ‘P’ when using the project ID in your API requests).

For example, in API request, GET index.php?/api/v2/get_project/{project_id}, replace {project_id} with 3.

So, the request would look like GET index.php?/api/v2/get_project/3.

Case ID – case_id

1. Go to the ‘Dashboard’ on your TestRail instance.
2. Select a project from the list.
3. Navigate to the ‘Test Cases’ tab.
4. Select a test case from the list.
5. Check the URL. The numeric character you see at the end is Test Case ID, or you can also get the ID next to Test Case Name. Please make sure to omit the character ‘C’ when using API requests.

Attachment ID – attachment_id

1. Go to the ‘Dashboard’ on your TestRail instance.
2. Select a project from the list.
3. Navigate to the ‘Test Cases’ tab.
4. Select a test case from the list.
5. Add an attachment.

For TestRail versions before 7.1 – Right-click on an attachment and select ‘Copy link address’. And, then use the attachment ID mentioned in the URL.

For TestRail version 7.1 and later – Click on the attachment. Then copy the alphanumeric ID from the URL on ‘Attachment Details’ screen.

Milestone ID – milestone_id

1. Go to the ‘Dashboard’ on your TestRail instance.
2. Select a project from the list.
3. Navigate to the ‘Milestones’ tab.
4. Select a milestone from the list.
5. Check the URL. The numeric character you see at the end is Milestone ID, or you can also get the ID next to Milestone Name. Please make sure to omit the character ‘M’ when using API requests.

Test Plan ID – plan_id

1. Go to the ‘Dashboard’ on your TestRail instance.
2. Select a project from the list.
3. Navigate to the ‘Test Runs and Results’ tab.
4. Select a test plan from the list.
5. Check the URL. The numeric character you see at the end is Test Plan ID, or you can also get the ID next to Test Plan Name. Please make sure to omit the character ‘R’ when using API requests.

Test Run ID – run_id

1. Go to the ‘Dashboard’ on your TestRail instance.
2. Select a project from the list.
3. Navigate to the ‘Test Runs and Results’ tab.
4. Select a test run from the list.
5. Check the URL. The numeric character you see at the end is Test Run ID, or you can also get the ID next to Test Run Name. Please make sure to omit the character ‘R’ when using API requests.