API: Milestones - TestRail

API: Milestones

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

On this page:

    API Rate Limit

    Please note that the API is rate-limited on TestRail Cloud to ensure optimal performance for all users and may throttle requests. TestRail might also return a 429 Too Many Requests response, which you are expected to handle. Such a response also includes a Retry-After header indicating how many seconds to wait before you are allowed to submit the next request.

    To avoid rate limits on TestRail Cloud, try using bulk API endpoints (e.g. using as add_results_for_cases instead of add_results_for case), build a time delay into your API calls, or upgrade to TestRail Enterprise Cloud.

    Rate limits for TestRail Cloud are as follows:

    • 180 Requests per instance, per minute for TestRail Cloud Professional subscriptions.
    • 300 Requests per instance, per minute for TestRail Cloud Enterprise subscriptions.

    No API rate limits are built into TestRail Server installations.

    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