Group milestones API

Use the group milestones using the REST API. There’s a separate project milestones API page.

List group milestones

Returns a list of group milestones.

GET /groups/:id/milestones
GET /groups/:id/milestones?iids[]=42
GET /groups/:id/milestones?iids[]=42&iids[]=43
GET /groups/:id/milestones?state=active
GET /groups/:id/milestones?state=closed
GET /groups/:id/milestones?title=1.0
GET /groups/:id/milestones?search=version
GET /groups/:id/milestones?updated_before=2013-10-02T09%3A24%3A18Z
GET /groups/:id/milestones?updated_after=2013-10-02T09%3A24%3A18Z

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group owned by the authenticated user
iids[]integer arraynoReturn only the milestones having the given iid (Note: ignored if include_parent_milestones is set as true)
statestringnoReturn only active or closed milestones
titlestringnoReturn only the milestones having the given title
searchstringnoReturn only milestones with a title or description matching the provided string
include_parent_milestonesbooleannoInclude milestones from parent group and its ancestors. Introduced in GitLab 13.4
updated_beforedatetimenoReturn only milestones updated before the given datetime. Expected in ISO 8601 format (2019-03-15T08:00:00Z). Introduced in GitLab 15.10
updated_afterdatetimenoReturn only milestones updated after the given datetime. Expected in ISO 8601 format (2019-03-15T08:00:00Z). Introduced in GitLab 15.10
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/milestones"

Example Response:

[
  {
    "id": 12,
    "iid": 3,
    "group_id": 16,
    "title": "10.0",
    "description": "Version",
    "due_date": "2013-11-29",
    "start_date": "2013-11-10",
    "state": "active",
    "updated_at": "2013-10-02T09:24:18Z",
    "created_at": "2013-10-02T09:24:18Z",
    "expired": false,
    "web_url": "https://gitlab.com/groups/gitlab-org/-/milestones/42"
  }
]

Get single milestone

Gets a single group milestone.

GET /groups/:id/milestones/:milestone_id

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group owned by the authenticated user
milestone_idintegeryesThe ID of the group milestone

Create new milestone

Creates a new group milestone.

POST /groups/:id/milestones

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group owned by the authenticated user
titlestringyesThe title of a milestone
descriptionstringnoThe description of the milestone
due_datedatenoThe due date of the milestone, in ISO 8601 format (YYYY-MM-DD)
start_datedatenoThe start date of the milestone, in ISO 8601 format (YYYY-MM-DD)

Edit milestone

Updates an existing group milestone.

PUT /groups/:id/milestones/:milestone_id

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group owned by the authenticated user
milestone_idintegeryesThe ID of a group milestone
titlestringnoThe title of a milestone
descriptionstringnoThe description of a milestone
due_datedatenoThe due date of the milestone, in ISO 8601 format (YYYY-MM-DD)
start_datedatenoThe start date of the milestone, in ISO 8601 format (YYYY-MM-DD)
state_eventstringnoThe state event of the milestone (close or activate)

Delete group milestone

Only for users with the Developer role in the group.

DELETE /groups/:id/milestones/:milestone_id

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group owned by the authenticated user
milestone_idintegeryesThe ID of the group’s milestone

Get all issues assigned to a single milestone

Gets all issues assigned to a single group milestone.

GET /groups/:id/milestones/:milestone_id/issues

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group owned by the authenticated user
milestone_idintegeryesThe ID of a group milestone

Currently, this API endpoint doesn’t return issues from any subgroups. If you want to get all the milestones’ issues, you can instead use the List issues API and filter for a particular milestone (for example, GET /issues?milestone=1.0.0&state=opened).

Get all merge requests assigned to a single milestone

Gets all merge requests assigned to a single group milestone.

GET /groups/:id/milestones/:milestone_id/merge_requests

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group owned by the authenticated user
milestone_idintegeryesThe ID of a group milestone

Get all burndown chart events for a single milestone

Version history
  • Introduced in GitLab 12.1
  • Moved to GitLab Premium in 13.9.

Get all burndown chart events for a single milestone.

GET /groups/:id/milestones/:milestone_id/burndown_events

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group owned by the authenticated user
milestone_idintegeryesThe ID of a group milestone