Join 34,000+ subscribers and receive articles from our blog about software quality, testing, QA and security.

API documentation for APIs which are limited to 250 results


Hi Dennis / Tobias,

I’ve been banging my head against a wall for a little while wondering why I weren’t seeing all of the available test plans via the get_plans api call.

After attempting to set the limit parameter to 500 and seeing the API error message “maximum 250” I know now what the limit is.

Can this:

a) Be documented somewhere if it isn’t already (I didn’t find mention of it on the get_plans API reference)?
b) Be handled in a way that allows our API calls to be more efficient?

For b), I can add some code to our TestRail interface to check if there are 250 results returned and then attempt another call with the offset set to 250, but I’m not sure this is ideal (imagine the scenario where there are exactly 250 results - we’d waste an API call asking for more data that doesn’t exist).

It would be better if the results json object contained some metadata to show that there are N results in total / N more results to retrieve, however that would most likely break the existing data structure… adding a parameter to the api method to return this metadata on top of the current data would be good enough for us though.


[{'total_rows': 762, 'data' : 
    {'assignedto_id': None,


Hi Glenn,

Thanks for your posting. All API functions with a :limit parameter use 250 as maximum value. This only affects a small number of API methods (get_plans/get_runs/get_results*), but I agree that this should be documented. Happy to look into this, thanks for your feedback!



After some experimentation we learned that passing &offset=N we can get the remaining records.


curl --insecure -H “Content-Type: application/json” -u “user@domain:URkI2eaSDRMs5IHEdf7N-PLEJX7fZ6Ycudrwy3SIf” “https://testrail/testrail/index.php?/api/v2/get_plans/6&offset=250


Hi Marcio,

Thanks for the update and providing the example! This looks to be very helpful in these scenarios.



I’m pretty sure I already covered that with: