Group milestones API

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

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?search_title=17.3+17.4
GET /groups/:id/milestones?search_title=17.3%2017.4
GET /groups/:id/milestones?updated_before=2013-10-02T09%3A24%3A18Z
GET /groups/:id/milestones?updated_after=2013-10-02T09%3A24%3A18Z
GET /groups/:id/milestones?containing_date=2013-10-02T09%3A24%3A18Z
GET /groups/:id/milestones?start_date=2013-10-02T09%3A24%3A18Z&end_date=2013-11-02T09%3A24%3A18Z

Parameters:

Attribute	Type	Required	Description
`id`	integer/string	yes	The ID or URL-encoded path of the group.
`iids[]`	integer array	no	Return only the milestones having the given `iid`. Ignored if `include_ancestors` is `true`.
`state`	string	no	Return only `active` or `closed` milestones.
`title`	string	no	Return only the milestones having the given `title` (case-sensitive).
`search`	string	no	Return only milestones with a title or description matching the provided string (case-insensitive).
`search_title`	string	no	Return only milestones with a title matching the provided string (case-insensitive). Multiple terms can be provided, separated by an escaped space, either `+` or `%20`, and will be ANDed together. Example: `17.4+17.5` will match substrings `17.4` and `17.5` (in any order). Introduced in GitLab 11.8.
`include_parent_milestones`	boolean	no	Deprecated in GitLab 16.7. Use `include_ancestors` instead.
`include_ancestors`	boolean	no	Include milestones for all parent groups.
`include_descendants`	boolean	no	Include milestones for group and its descendants. Introduced in GitLab 16.7.
`updated_before`	datetime	no	Return only milestones updated before the given datetime. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). Introduced in GitLab 15.10.
`updated_after`	datetime	no	Return only milestones updated after the given datetime. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). Introduced in GitLab 15.10.
`containing_date`	datetime	no	Return only milestones where `start_date <= containing_date <= due_date`. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). Introduced in GitLab 13.5.
`start_date`	datetime	no	Return only milestones where `due_date >=` the provided `start_date`. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). Note: only valid if `end_date` is also provided. Introduced in GitLab 12.8.
`end_date`	datetime	no	Return only milestones where `start_date <=` the provided `end_date`. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). Note: only valid if `start_date` is also provided. Introduced in GitLab 12.8.

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:

Attribute	Type	Required	Description
`id`	integer/string	yes	The ID or URL-encoded path of the group
`milestone_id`	integer	yes	The ID of the group milestone

Create new milestone

Creates a new group milestone.

POST /groups/:id/milestones

Parameters:

Attribute	Type	Required	Description
`id`	integer/string	yes	The ID or URL-encoded path of the group
`title`	string	yes	The title of a milestone
`description`	string	no	The description of the milestone
`due_date`	date	no	The due date of the milestone, in ISO 8601 format (`YYYY-MM-DD`)
`start_date`	date	no	The 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:

Attribute	Type	Required	Description
`id`	integer/string	yes	The ID or URL-encoded path of the group
`milestone_id`	integer	yes	The ID of a group milestone
`title`	string	no	The title of a milestone
`description`	string	no	The description of a milestone
`due_date`	date	no	The due date of the milestone, in ISO 8601 format (`YYYY-MM-DD`)
`start_date`	date	no	The start date of the milestone, in ISO 8601 format (`YYYY-MM-DD`)
`state_event`	string	no	The state event of the milestone (`close` or `activate`)

Delete group milestone

Only for users with the Developer role for the group.

DELETE /groups/:id/milestones/:milestone_id

Parameters:

Attribute	Type	Required	Description
`id`	integer/string	yes	The ID or URL-encoded path of the group
`milestone_id`	integer	yes	The 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:

Attribute	Type	Required	Description
`id`	integer/string	yes	The ID or URL-encoded path of the group
`milestone_id`	integer	yes	The 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:

Attribute	Type	Required	Description
`id`	integer/string	yes	The ID or URL-encoded path of the group
`milestone_id`	integer	yes	The ID of a group milestone

Get all burndown chart events for a single milestone

Tier: Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Get all burndown chart events for a single milestone.

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

Parameters:

Attribute	Type	Required	Description
`id`	integer/string	yes	The ID or URL-encoded path of the group
`milestone_id`	integer	yes	The ID of a group milestone

Docs

Edit this page to fix an error or add an improvement in a merge request.

Create an issue to suggest an improvement to this page.

Product

Create an issue if there's something you don't like about this feature.

Propose functionality by submitting a feature request.

Feature availability and product trials

View pricing to see all GitLab tiers and features, or to upgrade.

Try GitLab for free with access to all features for 30 days.

Get help

If you didn't find what you were looking for, search the docs.

If you want help with something specific and could use community support, post on the GitLab forum.

For problems setting up or using this feature (depending on your GitLab subscription).

Request support

Group milestones API

List group milestones

Get single milestone

Create new milestone

Edit milestone

Delete group milestone

Get all issues assigned to a single milestone

Get all merge requests assigned to a single milestone

Get all burndown chart events for a single milestone

Help & feedback

Docs

Product

Feature availability and product trials

Get help