API: Milestones - TestRail

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}

    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 body

    The following filters can be applied:

    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.

    Parameters

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

    Request body

    The following filters can be applied:

    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

    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

    info Please Note: Deleting a milestone cannot be undone.

    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)