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

How to get/update case ids in a test plan or run using API


Hi There,

I’m new to TestRail, not sure about this. I’m trying the using the API the add a test plan entry for test runs. But I cannot find ‘case_ids’ in test plan entry ‘runs’. Can I update the entry adding more test case ids?



Hi Tony,

Thanks for your posting. You can find the list of selected cases/tests in a run via get_tests:

This also applies to runs inside a plan. The case_ids attribute is currently not directly returned by add_run/add_plan or get_run/get_plan but you can use get_tests to get the included tests and their case IDs (case_id attribute).



Thank you Tobias! Now I can get the case ids. Can I use the API to update the case ids, especially when include_all is false?


Hi Tony,

You are welcome! Yes, you can use update_plan_entry to update the case selection for runs in plans or update_run for standalone runs.




I interpret Tobias’ reply in such way that with “update_plan_entry” it should be possible to update the “case_ids”-attribute of individual runs (non-standalone). However from my experience “update_plan_entry” has no access to the entry’s “runs”-array and hence can’t modify the case ids of the individual runs. Modifying the entry’s “case_ids”-attribute on the other hand is perfectly possible (but in my scenario of no use since the underlying runs overwrite it).
So am I doing something wrong or did I misunderstand Tobias’ reply?



Hi Julianm,

Thank you for the follow up. The update_plan_entry method would allow you to specify a case array using the case_ids POST field.

In order to do this however you will need the entry ID of the test run within your test plan. This is a alpha-numeric ID assigned to each test run within a test plan.

Your request then would look something like this:


“desscription”: “A description for the test run”,
“case_ids”: [1234,2345],
“include_all”: false


Hello Marty,

thanks for your reply! Please take a look at the response content of “get_plan” ( It contains an array called “entries”. By using “update_plan_entry” I can (as you pointed out) modify some of the attributes of the objects in this array but unfortunately the one attribute I am particularly interested in (the “runs”-array) appears to be inaccessible. I thought i might be able to modify the individual runs by using “update_run” however this function can only be used with runs which aren’t part of a plan.
So since “update_plan_entry” can’t access the “runs”-array and “update_run” can only be used on standalone runs I assume that the run-objects can’t be modified by using the api once they were created, is this correct?

Edit: Well maybe my question was too low level and therefore unclear, sorry. In our current setup multiple automatic tests get executed nightly whose results get “uploaded” to testrail using either “add_plan_entry” or (if the run already exists) “add_results_for_cases”. However with the latter function we are having troubles: Sometimes it happens that a testcase is not yet included in an existing run and then “add_results_for_cases” fails with: “HTTP 400(“Field :results contains one or more invalid results (case C11728 unknown or not part of the test run”)”. I know that via UI I can solve this issue by manually adding the missing testcases however I would like to know whether this can be done via API. Please also take a look at the screenshot I prepared which visualizes my experience with “update_plan_entry” and (hopefully) makes clear what I need.



It would really help if get_run() would return a list of included case IDs. Or even better, allow adding(removing) cases without having to set the complete list.

We need to update runs via the API and add more cases to it. update_run() needs a list of case IDs, but does not allow to add cases but only set the complete list. So we need the complete list of cases currently on the run first. We can go via get_tests(:run_id) but this gives us an array including hashes and we have to first extract all the case IDs from that. Not very convenient.


Thanks for your feedback! Yes, including the list of cases for get_run/get_plan is something that’s on our list of things to look into but we currently recommend using get_tests to get the actual case selection.



Hi Tobias,

Could you please elaborate on how to use get_tests to retrieve case_ids as part of a run inside a test plan? I need direction on how to convert a plan entry id into a run id (potentially UDID?).

You mentioned on your first reply that “This also applies to runs inside a plan”, yet the API returns response code 400 (invalid test run id) when passing a test plan entry id to get_tests. Also the Tests API documentation does not make any mention of using it for test plans.

To further reiterate @bullrich point, the update_run/plan/plan_entry would be more useful if the complete list of case_ids were not required when setting the custom case selection. Append functionality for this field would be far more convenient so that the existing case_ids in a run would not need to be fetched for every update call. Maybe simply adding an append boolean field could make this a less impactful implementation to your customers.

*Edit: I figured out the dissonance was that I needed to iterate through the TestRuns within the TestPlanEntry that matched my query to retrieve the run id.


Purely as a FYI - Tobias and Dennis Gurock are no longer with the company. No idea if anyone is monitoring when the tagging is being used in posts but I would not necessarily bet on it…