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

Get Milestones + Sub Milestones


Hello Everyone,

I’m trying to use the new Sub Milestones system, but when i’m using the REST API asking for Milestones, it seems that submilestones aren’t return.

Did i miss something ?



Hi Joris,

Thanks for your posting! get_milestones only includes the root-level milestones, but you can get_milestone per milestone to get the sub-milestones for a milestone.

I hope this helps!



Not really sorry…

The idea is to easily get all milestones including sub milestones, as, at this point i don’t know their IDs.


Hi Joris,

The idea is to call get_milestones once (for the project; with or without filters) and this includes the IDs in the response. You can then call get_milestone per milestone. We don’t include the sub-milestones in get_milestones directly because this may not scale well for long-running projects with lots of milestones and sub-milestones/iterations/sprints.



Hello Tobias

In the API Description for Milestones ( one of the response content fields for get_milestone and get_milestones is

Name: "milestones"
Type: "array"
Description: “The sub milestones that belong to the milestone (if any); only available with get_milestone (available since TestRail 5.3)”

We are running TestRail v5.3.0.3603.

When I call get_milestone or get_milestones the response content is:

“id”: 1,
“name”: “…”,
“description”: null,
“start_on”: 1488326400,
“started_on”: null,
“is_started”: false,
“due_on”: 1501459200,
“is_completed”: false,
“completed_on”: null,
“project_id”: 2,
“parent_id”: null,
“url”: “http://…”

As you can see, that there is no “milestones” field, but I know, that this Milestone has a child.
My question: what do I do wrong? Why is there no “milestones” field?

Thank you for your Answer in advance



Hi Cac,

Thanks for your reply! The get_milestones method would only return a list of the parent milestones currently. That said, you can query the parent milestones from that response using get_milestone to view the milestones field which would contain the sub-milestones. This would always contain the milestones field if the milestone contains sub-milestones. I would just recommend double checking the ID for the parent milestone (and you can even do this in the UI by navigating to the milestone and checking the ID number in the URL) to ensure you’re making the correct call. Hope this helps!



Are there any enhancements planned? Querying every milestone for sub-milestones is rather slow.

What would be very helpful:

  1. get_milestones entries having a key to tell us if the milestone has sub-milestones or not (to reduce queries)
  2. get_milestones having a flag to allow us to return sub-milestones


I’m just playing with this at the moment - any chance of an example from anyone, I’m not quite sure I understand the solution here.

Our ‘top level’ milestones run 1 to 40, but we have many many ‘sub-milestones’.

I’m trying to get the details of milestone 245 which is a sub-milestone of milestone 40 for example.

Simply using ‘get_milestones/245’ doesn’t work (php), and I’m unsure how to “…query the parent milestones…” as mentioned in @mgarcia’s post dated 15th March above.

Any help would be greatly appreciated! :slight_smile: