API: Milestones
Use the following API methods to request details about milestones and to create or modify milestones.
On this page:
get_milestone
Returns an existing milestone.
GET index.php?/api/v2/get_milestone/:milestone_id
:milestone_id | The ID of the milestone |
Response content
Please see below for a typical example response:
{ "completed_on": 1389968184, "description": "...", "due_on": 1391968184, "id": 1, "is_completed": true, "name": "Release 1.5", "project_id": 1,
"refs": "RF-1, RF-2", "url": "http:///testrail/index.php?/milestones/view/1" }
The following fields are included in the response:
Name | Type | Description |
---|---|---|
completed_on | timestamp | The date/time when the milestone was marked as completed (as UNIX timestamp) |
description | string | The description of the milestone |
due_on | timestamp | The due date/time of the milestone (as UNIX timestamp) |
id | int | The unique ID of the milestone |
is_completed | bool | True if the milestone is marked as started and false otherwise |
is_started | bool | True if the milestone is marked as started and false otherwise (available since TestRail 5.3) |
milestones | array | The sub milestones that belong to the milestone (if any); only available with get_milestone (available since TestRail 5.3) |
name | string | The name of the milestone |
parent_id | int | The ID of the parent milestone the milestone belongs to (if any) (available since TestRail 5.3) |
project_id | int | The ID of the project the milestone belongs to |
refs | string | A comma-separated list of references/requirements (available since TestRail 6.4) |
start_on | timestamp | The scheduled start date/time of the milestone (as UNIX timestamp) (available since TestRail 5.3) |
started_on | timestamp | The date/time when the milestone was started (as UNIX timestamp) (available since TestRail 5.3) |
url | string | The address/URL of the milestone in the user interface |
Response codes
200 | Success, the milestone is returned as part of the response |
400 | Invalid or unknown milestone |
403 | No access to the project |
get_milestones
Returns the list of milestones for a project.
GET index.php?/api/v2/get_milestones/:project_id
:project_id | The ID of the project |
Request filters
The following filters can be applied:
Name | Type | Description |
---|---|---|
:is_completed | bool | 1 to return completed milestones only. 0 to return open (active/upcoming) milestones only. |
:is_started | bool | 1 to return started milestones only. 0 to return upcoming milestones only (available since TestRail 5.3) |
:limit | integer | The number of milestones the response should return (The response size is 250 by default) (requires TestRail 6.7 or later) |
:offset | integer | Where to start counting the milestones from (the offset) (requires TestRail 6.7 or later) |
# All active milestones for project with ID 1
GET index.php?/api/v2/get_milestones/1&is_completed=0
Response content
The response includes an array of milestones. Each milestone in this list follows the same format as get_milestone.
[
{ "id": 1, "name": "Release 1.5", .. },
{ "id": 2, "name": "Release 1.6", .. },
..
]
info Please Note: As of February 26, 2021 the data structure returned by bulk GET API endpoints will change. These bulk endpoints will no longer return an array of all entities, but will instead return an object with additional pagination fields and an array of up to 250 entities.To see the new response structure and test any necessary code changes, include the following header and value in your API requests: x-api-ident: beta.
New Response Content
The response includes an array of milestones. Each milestone in this list follows the same format as get_milestone.
{
"offset": 0,
"limit": 250,
"size": 5,
"_links": {
"next": null,
"prev": null,
},
"milestones": [ { "id": 1, "name": "Release 1.5", .. }, { "id": 2, "name": "Release 1.6", .. }, .. ]
}
Response codes
200 | Success, the milestones are returned as part of the response |
400 | Invalid or unknown project |
403 | No access to the project |
add_milestone
Creates a new milestone.
POST index.php?/api/v2/add_milestone/:project_id
:project_id | The ID of the project the milestone should be added to |
Request fields
The following POST fields are supported:
Name | Type | Description |
---|---|---|
name | string | The name of the milestone (required) |
description | string | The description of the milestone |
due_on | timestamp | The due date of the milestone (as UNIX timestamp) |
parent_id | int | The ID of the parent milestone, if any (for sub-milestones) (available since TestRail 5.3) |
refs | string | A comma-separated list of references/requirements (available since TestRail 6.4) |
start_on | timestamp | The scheduled start date of the milestone (as UNIX timestamp) (available since TestRail 5.3) |
Request example
Also see below for an example on how to create a new, empty milestone with a due date:
{ "name": "Release 2.0", "due_on": 1394596385 }
Response content
If successful, this method returns the new milestone using the same response format as get_milestone.
Response codes
200 | Success, the milestone was created and is returned as part of the response |
400 | Invalid or unknown project |
403 | No permissions to add milestones or no access to the project |
update_milestone
Updates an existing milestone (partial updates are supported, i.e. you can submit and update specific fields only).
POST index.php?/api/v2/update_milestone/:milestone_id
:milestone_id | The ID of the milestone |
Request fields
In addition to the POST fields supported by add_milestone, this method also supports:
Name | Type | Description |
---|---|---|
is_completed | bool | True if a milestone is considered completed and false otherwise |
is_started | bool | True if a milestone is considered started and false otherwise |
parent_id | int | The ID of the parent milestone, if any (for sub-milestones) (available since TestRail 5.3) |
start_on | timestamp | The scheduled start date of the milestone (as UNIX timestamp) (available since TestRail 5.3) |
Request example
Also see below for an example on how to mark a milestone as completed:
{ "is_completed": true }
Response content
If successful, this method returns the updated milestone using the same response format as get_milestone.
Response codes
200 | Success, the milestone was updated and is returned as part of the response |
400 | Invalid or unknown milestone |
403 | No permissions to modify milestones or no access to the project |
delete_milestone
Deletes an existing milestone.
POST index.php?/api/v2/delete_milestone/:milestone_id
:milestone_id | The ID of the milestone |
info Please Note: Deleting a milestone cannot be undone.
Response codes
200 | Success, the milestone was deleted |
400 | Invalid or unknown milestone |
403 | No permissions to delete milestones or no access to the project |