API: Introduction - TestRail

API: Introduction

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.

The API is part of TestRail and can be enabled in TestRail’s administration area under Administration > Site Settings > API.

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
Before reading through the API reference, please make yourself familiar with TestRail’s entities such as cases, runs & results, suites etc. To do this, please refer to TestRail’s User Guide with getting started topics and best practices.

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.

No API rate limits are built into TestRail Server installations.