Project milestones API

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

List project milestones

Returns a list of project milestones. 

GET /projects/:id/milestones
GET /projects/:id/milestones?iids[]=42
GET /projects/:id/milestones?iids[]=42&iids[]=43
GET /projects/:id/milestones?state=active
GET /projects/:id/milestones?state=closed
GET /projects/:id/milestones?title=1.0
GET /projects/:id/milestones?search=version

Parameters:

Attribute Type Required Description
id integer or string yes The ID or URL-encoded path of the project owned by the authenticated user
iids[] integer array optional Return only the milestones having the given iid (Note: ignored if include_parent_milestones is set as true)
state string optional Return only active or closed milestones
title string optional Return only the milestones having the given title
search string optional Return only milestones with a title or description matching the provided string
include_parent_milestones boolean optional Include group milestones from parent group and its ancestors. 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/milestones"

Example Response: 

[
  {
    "id": 12,
    "iid": 3,
    "project_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
  }
]

Get single milestone

Gets a single project milestone. 

GET /projects/:id/milestones/:milestone_id

Parameters:

Attribute Type Required Description
id integer or string yes The ID or URL-encoded path of the project owned by the authenticated user
milestone_id integer yes The ID of the project’s milestone

Create new milestone

Creates a new project milestone. 

POST /projects/:id/milestones

Parameters:

Attribute Type Required Description
id integer or string yes The ID or URL-encoded path of the project owned by the authenticated user
title string yes The title of a milestone
description string no The description of the milestone
due_date string no The due date of the milestone
start_date string no The start date of the milestone

Edit milestone

Updates an existing project milestone. 

PUT /projects/:id/milestones/:milestone_id

Parameters:

Attribute Type Required Description
id integer or string yes The ID or URL-encoded path of the project owned by the authenticated user
milestone_id integer yes The ID of the project’s milestone
title string no The title of a milestone
description string no The description of the milestone
due_date string no The due date of the milestone
start_date string no The start date of the milestone
state_event string no The state event of the milestone (close or activate)

Delete project milestone

Only for users with the Developer role in the project. 

DELETE /projects/:id/milestones/:milestone_id

Parameters:

Attribute Type Required Description
id integer or string yes The ID or URL-encoded path of the project owned by the authenticated user
milestone_id integer yes The ID of the project’s milestone

Get all issues assigned to a single milestone

Gets all issues assigned to a single project milestone. 

GET /projects/:id/milestones/:milestone_id/issues

Parameters:

Attribute Type Required Description
id integer or string yes The ID or URL-encoded path of the project owned by the authenticated user
milestone_id integer yes The ID of the project’s milestone

Get all merge requests assigned to a single milestone

Gets all merge requests assigned to a single project milestone. 

GET /projects/:id/milestones/:milestone_id/merge_requests

Parameters:

Attribute Type Required Description
id integer or string yes The ID or URL-encoded path of the project owned by the authenticated user
milestone_id integer yes The ID of the project’s milestone

Promote project milestone to a group milestone

Only for users with the Developer role in the group. 

POST /projects/:id/milestones/:milestone_id/promote

Parameters:

Attribute Type Required Description
id integer or string yes The ID or URL-encoded path of the project owned by the authenticated user
milestone_id integer yes The ID of the project’s milestone

Get all burndown chart events for a single milestone

Version history

Gets all burndown chart events for a single milestone. 

GET /projects/:id/milestones/:milestone_id/burndown_events

Parameters:

Attribute Type Required Description
id integer or string yes The ID or URL-encoded path of the project owned by the authenticated user
milestone_id integer yes The ID of the project’s 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.
to help shape new features.
Feature availability and product trials
 to see all GitLab tiers and features, or to upgrade.
 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, .

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

Request support