Project milestones API

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

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

List project milestones

Returns a list of project milestones.

Copy to clipboard
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
GET /projects/:id/milestones?updated_before=2013-10-02T09%3A24%3A18Z
GET /projects/:id/milestones?updated_after=2013-10-02T09%3A24%3A18Z

Parameters:

Attribute Type Required Description
id integer or string yes The ID or URL-encoded path of the project
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
search string no Return only milestones with a title or description matching the provided string
include_parent_milestones boolean no Deprecated in GitLab 16.7. Use include_ancestors instead.
include_ancestors boolean no Include milestones from all parent groups.
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
Copy to clipboard
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/milestones"

Example Response:

Copy to clipboard
[
  {
    "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.

Copy to clipboard
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
milestone_id integer yes The ID of the project’s milestone

Create new milestone

Creates a new project milestone.

Copy to clipboard
POST /projects/:id/milestones

Parameters:

Attribute Type Required Description
id integer or string yes The ID or URL-encoded path of the project
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 (YYYY-MM-DD)
start_date string no The start date of the milestone (YYYY-MM-DD)

Edit milestone

Updates an existing project milestone.

Copy to clipboard
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
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 (YYYY-MM-DD)
start_date string no The start date of the milestone (YYYY-MM-DD)
state_event string no The state event of the milestone (close or activate)

Delete project milestone

History

Only for users with at least the Planner role for the project.

Copy to clipboard
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
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.

Copy to clipboard
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
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.

Copy to clipboard
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
milestone_id integer yes The ID of the project’s milestone

Promote project milestone to a group milestone

History

Only for users with at least the Planner role for the group.

Copy to clipboard
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
milestone_id integer yes The ID of the project’s milestone

Get all burndown chart events for a single milestone

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

Gets all burndown chart events for a single milestone.

Copy to clipboard
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
milestone_id integer yes The ID of the project’s milestone