1. TestRail Support Center
  2. API Manual
  3. API reference

Milestones

Updated

Use the following API methods to request details about milestones and to create or modify milestones.

get_milestone

Returns an existing milestone.

GET index.php?/api/v2/get_milestone/{milestone_id}

Parameters

Name Type Required Description
milestone_id integer true 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 integer The unique ID of the milestone
is_completed boolean True if the milestone is marked as started and false otherwise
is_started boolean True if the milestone is marked as started and false otherwise — requires TestRail 5.3 or later.
milestones array The sub milestones that belong to the milestone (if any); only available with get_milestone — requires TestRail 5.3 or later
name string The name of the milestone
parent_id integer The ID of the parent milestone the milestone belongs to (if any) — requires TestRail 5.3 or later
project_id integer The ID of the project the milestone belongs to
refs string A comma-separated list of references/requirements — requires TestRail 6.4 or later
start_on timestamp The scheduled start date/time of the milestone (as UNIX timestamp) — requires TestRail 5.3 or later
started_on timestamp The date/time when the milestone was started (as UNIX timestamp) — requires TestRail 5.3 or later
url string The address/URL of the milestone in the user interface

Response codes

Status Code Description
200 Success (the milestone is returned as part of the response)
400 Invalid or unknown milestone
403 No access to the project
429

TestRail Cloud only—Too many requests (see API rate limit)

get_milestones

Returns the list of milestones for a project.

GET index.php?/api/v2/get_milestones/{project_id}

Parameters

Name Type Required Description
project_id integer true The ID of the project

Request filters

The following filters can be applied as query parameters in the request URL:

Name Type Description
is_completed boolean 1 to return completed milestones only. 0 to return open (active/upcoming) milestones only
is_started boolean 1 to return started milestones only. 0 to return upcoming milestones only — requires TestRail 5.3 or later
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.

{
    "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

Status Code Description
200 Success (the milestones are returned as part of the response)
400 Invalid or unknown project
403 No access to the project
429

TestRail Cloud only—Too many requests (see API rate limit)

add_milestone

Creates a new milestone.

POST index.php?/api/v2/add_milestone/{project_id}

Parameters

Name Type Required Description
project_id integer true The ID of the project the milestone should be added to

Request filters

The following filters can be applied as query parameters in the request URL:

Name Type Required Description
name string true The name of the milestone
description string false The description of the milestone
due_on timestamp false The due date of the milestone (as UNIX timestamp)
parent_id integer false The ID of the parent milestone, if any (for sub-milestones) — requires TestRail 5.3 or later
refs string false A comma-separated list of references/requirements — requires TestRail 6.4 or later
start_on timestamp false The scheduled start date of the milestone (as UNIX timestamp) — requires TestRail 5.3 or later

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

Status Code Description
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
429

TestRail Cloud only—Too many requests (see API rate limit)

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}

Parameters

Name Type Required Description
milestone_id integer true The ID of the milestone

Request body

The following filters can be applied in the request body:

Name Type Description
is_completed boolean True if a milestone is considered completed and false otherwise
is_started boolean True if a milestone is considered started and false otherwise
parent_id integer The ID of the parent milestone, if any (for sub-milestones)— requires TestRail 5.3 or later
start_on timestamp The scheduled start date of the milestone (as UNIX timestamp) — requires TestRail 5.3 or later

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

Status Code Description
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
429

TestRail Cloud only—Too many requests (see API rate limit)

delete_milestone

 

Deleting a milestone cannot be undone.

Deletes an existing milestone.

POST index.php?/api/v2/delete_milestone/{milestone_id}

Parameters

Name Type Required Description
milestone_id integer true The ID of the milestone

Response codes

Status Code Description
200 Success (the milestone was deleted)
400 Invalid or unknown milestone
403 No permissions to delete milestones or no access to the project
429

TestRail Cloud only—Too many requests (see API rate limit)
Was this article helpful?
4 out of 7 found this helpful