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