Milestones

The milestones namespace provides API methods to retrieve all or specific milestones for a project. This page covers the following API methods:

GET /projects/{project_id}/milestones

Returns all milestones for a project.

This method uses pagination so you might need to request additional pages to retrieve all milestones.

project_id id required ID of the project.

Request

page integer Number of page to return (default: first page)

per_page integer Maximum number of milestones to return (supported: 15, 25, 50, 100; default: 100)

sort string Sort field for the list of milestones (supported: milestones:created_at, milestones:completed_at; default: milestones:created_at)

order string Sort order (ascending or descending) (supported: asc, desc; default: desc)

automation_tags string Comma-separated list of automation tags to filter by.

completed_after string Limit result to milestones completed after (in ISO8601 format and UTC time zone).

completed_before string Limit result to milestones completed before (in ISO8601 format and UTC time zone).

created_after string Limit result to milestones created after (in ISO8601 format and UTC time zone).

created_before string Limit result to milestones created before (in ISO8601 format and UTC time zone).

created_by string Comma-separated list of users to filter by.

is_completed boolean Limit result to active or completed milestones only.

parent_id string Comma-separated list of parent milestones to filter by.

root_id string Comma-separated list of root milestones to filter by.

type_id string Comma-separated list of milestone types to filter by.

expands string Comma-separated list of expands to return.

This method supports the following expands so you can automatically include additional information for referenced objects:

  • issues

  • milestone_stats

  • milestone_types

  • milestones

  • statuses

  • users

Response

GET /api/v1/projects/1/milestones
200 OK
{
    "page": 1,
    "prev_page": null,
    "next_page": 2,
    "last_page": 2,
    "per_page": 100,
    "total": 150,
    "result": [
        {
            "id": 1,
            "project_id": 1,
            "root_id": null,
            "parent_id": null,
            "name": "Milestone 1",
            ..
            "is_completed": false,
            "created_at": "..",
            "created_by": 2,
            "updated_at": null,
            "updated_by": null,
            "completed_at": null
        },
        {
            "id": 2,
            "project_id": 1,
            "root_id": null,
            "parent_id": null,
            "name": "Milestone 2",
            ..
            "is_completed": true,
            "created_at": "..",
            "created_by": 2,
            "updated_at": null,
            "updated_by": null,
            "completed_at": ".."
        },
        ..
    ],
    "expands": {
        ..
    }
}

Examples

// Get latest 100 milestones for project with ID 5
GET /api/v1/projects/5/milestones

// Get second result page (pagination)
GET /api/v1/projects/5/milestones?page=2

// Get latest 100 active milestones
GET /api/v1/projects/5/milestones?is_completed=0

// Get latest 100 completed milestones, ordered by completion date
GET /api/v1/projects/5/milestones?is_completed=1&sort=milestones:completed_at

// Get latest milestones created after a certain date & time
GET /api/v1/projects/5/milestones?created_after=2023-02-15T00:00:00.000Z

// Get milestones and include expands
GET /api/v1/projects/5/milestones?expands=issues,milestone_types,users

Status codes

200 400 401 403 422 (details)

GET /milestones/{milestone_id}

Returns a single milestone.

milestone_id id required ID of the milestone to return.

Request

expands string Comma-separated list of expands to return.

This method supports the following expands so you can automatically include additional information for referenced objects:

  • issues

  • milestone_stats

  • milestone_types

  • milestones

  • statuses

  • users

Response

GET /api/v1/milestones/1
200 OK
{
    "result": {
        "id": 1,
        "project_id": 1,
        "root_id": null,
        "parent_id": null,
        "name": "Milestone 1",
        ..
        "is_completed": false,
        "created_at": "..",
        "created_by": 2,
        "updated_at": null,
        "updated_by": null,
        "completed_at": null
    },
    "expands": {
        ..
    }
}

Examples

// Get the milestone with ID 5
GET /api/v1/milestones/5

// Get a milestone and include expands
GET /api/v1/milestones/1?expands=issues,milestone_types,users

Status codes

200 400 401 403 404 422 (details)

Last updated