Milestones

Use this API to manage milestones for both projects and groups.

List all group milestones

GET /api/v4/groups/{id}/milestones

Lists all group milestones for a specified group.

Parameters

Name	Type	Description
`id` Path, required	String	The ID of a group
`state` Query	String	Return “active”, “closed”, or “all” milestones Allowed values: `active`, `closed`, `all` Default: `all`
`iids` Query	Array of integers	The IIDs of the milestones
`title` Query	String	The title of the milestones
`search` Query	String	The search criteria for the title or description of the milestone
`include_parent_milestones` Query	Boolean	Deprecated: see `include_ancestors`. Mutually exclusive with `include_ancestors`
`include_ancestors` Query	Boolean	Include milestones from all parent groups. Mutually exclusive with `include_parent_milestones`
`updated_before` Query	String (date-time)	Return milestones updated before the specified datetime. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ
`updated_after` Query	String (date-time)	Return milestones updated after the specified datetime. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`
`include_descendants` Query	Boolean	Include milestones from all subgroups and subprojects

Responses

Code	Description	Schema
`200`	OK	APIEntitiesMilestone
`400`	Bad Request	—
`404`	Not Found	—

Create a group milestone

POST /api/v4/groups/{id}/milestones

Creates a milestone for the specified group.

Parameters

Name	Type	Description
`id` Path, required	String	The ID of a group

Request body (application/json)

Property	Type	Description
`description`	String	The description of the milestone
`due_date`	String	The due date of the milestone. The ISO 8601 date format (%Y-%m-%d)
`start_date`	String	The start date of the milestone. The ISO 8601 date format (%Y-%m-%d)
`title` Required	String	The title of the milestone

Responses

Code	Description	Schema
`201`	Created	APIEntitiesMilestone
`400`	Bad Request	—
`404`	Not Found	—

Retrieve a group milestone

GET /api/v4/groups/{id}/milestones/{milestone_id}

Retrieves a specified group milestone.

Parameters

Name	Type	Description
`id` Path, required	String	The ID of a group
`milestone_id` Path, required	Integer	The ID of a group milestone

Responses

Code	Description	Schema
`200`	OK	APIEntitiesMilestone
`400`	Bad Request	—
`404`	Not Found	—

Update a group milestone

PUT /api/v4/groups/{id}/milestones/{milestone_id}

Updates the specified group milestone.

Parameters

Name	Type	Description
`id` Path, required	String	The ID of a group
`milestone_id` Path, required	Integer	The milestone ID number

Request body (application/json)

Property	Type	Description
`description`	String	The description of the milestone
`due_date`	String	The due date of the milestone. The ISO 8601 date format (%Y-%m-%d)
`start_date`	String	The start date of the milestone. The ISO 8601 date format (%Y-%m-%d)
`state_event`	String	The state event of the milestone Allowed values: `close`, `activate`
`title`	String	The title of the milestone

Responses

Code	Description	Schema
`200`	OK	APIEntitiesMilestone
`400`	Bad Request	—
`404`	Not Found	—

Delete a group milestone

DELETE /api/v4/groups/{id}/milestones/{milestone_id}

Deletes the specified group milestone.

Parameters

Name	Type	Description
`id` Path, required	String	The ID of a group
`milestone_id` Path, required	Integer	The ID of a group milestone

Responses

Code	Description	Schema
`204`	204 No Content	—
`400`	Bad Request	—
`404`	Not Found	—

List all issues assigned to a single milestone

GET /api/v4/groups/{id}/milestones/{milestone_id}/issues

Lists all issues assigned to a specified group milestone.

Parameters

Name	Type	Description
`id` Path, required	String	The ID of a group
`milestone_id` Path, required	Integer	The ID of a group milestone
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesIssueBasic
`400`	Bad Request	—
`404`	Not Found	—

List all merge requests assigned to a single milestone

GET /api/v4/groups/{id}/milestones/{milestone_id}/merge_requests

Lists all merge requests assigned to a specified group milestone.

Parameters

Name	Type	Description
`id` Path, required	String	The ID of a group
`milestone_id` Path, required	Integer	The ID of a group milestone
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesMergeRequestBasic
`400`	Bad Request	—
`404`	Not Found	—

List all project milestones

GET /api/v4/projects/{id}/milestones

Lists all milestones for a specified project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`state` Query	String	Return “active”, “closed”, or “all” milestones Allowed values: `active`, `closed`, `all` Default: `all`
`iids` Query	Array of integers	The IIDs of the milestones
`title` Query	String	The title of the milestones
`search` Query	String	The search criteria for the title or description of the milestone
`include_parent_milestones` Query	Boolean	Deprecated: see `include_ancestors`. Mutually exclusive with `include_ancestors`
`include_ancestors` Query	Boolean	Include milestones from all parent groups. Mutually exclusive with `include_parent_milestones`
`updated_before` Query	String (date-time)	Return milestones updated before the specified datetime. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ
`updated_after` Query	String (date-time)	Return milestones updated after the specified datetime. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesMilestone
`400`	Bad Request	—
`404`	Not Found	—

Create a project milestone

POST /api/v4/projects/{id}/milestones

Creates a project milestone.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project

Request body (application/json)

Property	Type	Description
`description`	String	The description of the milestone
`due_date`	String	The due date of the milestone. The ISO 8601 date format (%Y-%m-%d)
`start_date`	String	The start date of the milestone. The ISO 8601 date format (%Y-%m-%d)
`title` Required	String	The title of the milestone

Responses

Code	Description	Schema
`201`	Created	APIEntitiesMilestone
`400`	Bad Request	—
`404`	Not Found	—

Retrieve a project milestone

GET /api/v4/projects/{id}/milestones/{milestone_id}

Retrieves a specified project milestone.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`milestone_id` Path, required	Integer	The ID of a project milestone

Responses

Code	Description	Schema
`200`	OK	APIEntitiesMilestone
`400`	Bad Request	—
`404`	Not Found	—

Update a project milestone

PUT /api/v4/projects/{id}/milestones/{milestone_id}

Updates a specified project milestone.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`milestone_id` Path, required	Integer	The milestone ID number

Request body (application/json)

Property	Type	Description
`description`	String	The description of the milestone
`due_date`	String	The due date of the milestone. The ISO 8601 date format (%Y-%m-%d)
`start_date`	String	The start date of the milestone. The ISO 8601 date format (%Y-%m-%d)
`state_event`	String	The state event of the milestone Allowed values: `close`, `activate`
`title`	String	The title of the milestone

Responses

Code	Description	Schema
`200`	OK	APIEntitiesMilestone
`400`	Bad Request	—
`404`	Not Found	—

Delete a project milestone

DELETE /api/v4/projects/{id}/milestones/{milestone_id}

Deletes a specified project milestone. Only for users with the Planner, Reporter, Developer, Maintainer, or Owner role for the project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`milestone_id` Path, required	Integer	The ID of a project milestone

Responses

Code	Description	Schema
`204`	No Content	—
`400`	Bad Request	—
`404`	Not Found	—

List all issues for a project milestone

GET /api/v4/projects/{id}/milestones/{milestone_id}/issues

Lists all issues assigned to a specified project milestone.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`milestone_id` Path, required	Integer	The ID of a project milestone
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesIssueBasic
`400`	Bad Request	—
`404`	Not Found	—

List all merge requests for a project milestone

GET /api/v4/projects/{id}/milestones/{milestone_id}/merge_requests

Lists all merge requests assigned to a specified project milestone.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`milestone_id` Path, required	Integer	The ID of a project milestone
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesMergeRequestBasic
`400`	Bad Request	—
`404`	Not Found	—

Promote a project milestone to a group milestone

POST /api/v4/projects/{id}/milestones/{milestone_id}/promote

Promotes a specified project milestone to a group milestone. Only for users with the Planner, Reporter, Developer, Maintainer, or Owner role for the group.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`milestone_id` Path, required	Integer	The ID of a project milestone

Responses

Code	Description	Schema
`201`	Created	—
`400`	Bad Request	—
`404`	Not Found	—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesCustomAttribute

Property	Type	Description
`key`	String	Example: `foo`
`value`	String	Example: `bar`

APIEntitiesIssuableReferences

Property	Type	Description
`full`	String	Example: `test&6`
`relative`	String	Example: `&6`
`short`	String	Example: `&6`

APIEntitiesIssuableTimeStats

Property	Type	Description
`human_time_estimate`	String	Example: `3h 30m`
`human_total_time_spent`	String	Example: `1h`
`time_estimate`	Integer	Example: `12600`
`total_time_spent`	Integer	Example: `3600`

APIEntitiesIssueBasic

Property	Type	Description
`assignee`	APIEntitiesUserBasic	—
`assignees`	APIEntitiesUserBasic	—
`author`	APIEntitiesUserBasic	—
`closed_at`	String (date-time)	Example: `2022-11-15T08:30:55.232Z`
`closed_by`	APIEntitiesUserBasic	—
`confidential`	Boolean	—
`created_at`	String (date-time)	Example: `2022-08-17T12:46:35.053Z`
`description`	String	Example: `Repellendus impedit et vel velit dignissimos.`
`discussion_locked`	Boolean	—
`downvotes`	Integer	—
`due_date`	String (date)	Example: `2022-11-20`
`id`	Integer (int64)	Example: `84`
`iid`	Integer	Example: `14`
`issue_type`	String	Example: `issue`
`labels`	Array of strings	Example: `["bug"]`
`merge_requests_count`	Integer	—
`milestone`	APIEntitiesMilestone	—
`project_id`	Integer (int64)	Example: `4`
`start_date`	String (date)	Example: `2022-11-18`
`state`	String	Example: `closed`
`task_completion_status`	APIEntitiesTaskCompletionStatus	—
`time_stats`	APIEntitiesIssuableTimeStats	—
`title`	String	Example: `Impedit et ut et dolores vero provident ullam est`
`type`	String	One of [“ISSUE”, “INCIDENT”, “TEST_CASE”, “REQUIREMENT”, “TASK”, “TICKET”] Example: `ISSUE`
`updated_at`	String (date-time)	Example: `2022-11-14T17:22:01.470Z`
`upvotes`	Integer	—
`user_notes_count`	Integer	—
`web_url`	String	Example: `http://example.com/example/example/issues/14`

APIEntitiesMergeRequestBasic

Property	Type	Description
`allow_collaboration`	Boolean	—
`allow_maintainer_to_push`	Boolean	—
`assignee`	APIEntitiesUserBasic	—
`assignees`	APIEntitiesUserBasic	—
`author`	APIEntitiesUserBasic	—
`blocking_discussions_resolved`	Boolean	—
`closed_at`	String (date-time)	Example: `2022-01-31T15:10:45.080Z`
`closed_by`	APIEntitiesUserBasic	—
`created_at`	String (date-time)	Example: `2022-08-17T12:46:35.053Z`
`description`	String	Example: `Repellendus impedit et vel velit dignissimos.`
`description_html`	String	—
`detailed_merge_status`	String	Example: `mergeable`
`discussion_locked`	Boolean	—
`downvotes`	Integer	—
`draft`	Boolean	—
`force_remove_source_branch`	Boolean	—
`has_conflicts`	Boolean	—
`id`	Integer (int64)	Example: `84`
`iid`	Integer	Example: `14`
`imported`	Boolean	—
`imported_from`	String	Example: `bitbucket`
`labels`	Array of strings	—
`merge_after`	String (date-time)	Example: `2022-01-31T15:10:45.080Z`
`merge_commit_sha`	String	Example: `1234abcd`
`merge_status`	String	Example: `unchecked`
`merge_user`	APIEntitiesUserBasic	—
`merge_when_pipeline_succeeds`	Boolean	—
`merged_at`	String (date-time)	Example: `2022-01-31T15:10:45.080Z`
`merged_by`	APIEntitiesUserBasic	—
`milestone`	APIEntitiesMilestone	—
`prepared_at`	String (date-time)	Example: `2022-01-31T15:10:45.080Z`
`project_id`	Integer (int64)	Example: `4`
`reference`	String	Example: `!1`
`references`	APIEntitiesIssuableReferences	—
`reviewers`	APIEntitiesUserBasic	—
`sha`	String	Example: `1234abcd`
`should_remove_source_branch`	Boolean	—
`source_branch`	String	—
`source_project_id`	Integer (int64)	—
`squash`	Boolean	—
`squash_commit_sha`	String	Example: `1234abcd`
`squash_on_merge`	Boolean	—
`state`	String	Example: `closed`
`target_branch`	String	—
`target_project_id`	Integer (int64)	—
`task_completion_status`	APIEntitiesTaskCompletionStatus	—
`time_stats`	APIEntitiesIssuableTimeStats	—
`title`	String	Example: `Impedit et ut et dolores vero provident ullam est`
`title_html`	String	—
`updated_at`	String (date-time)	Example: `2022-11-14T17:22:01.470Z`
`upvotes`	Integer	—
`user_notes_count`	Integer	—
`web_url`	String	Example: `https://gitlab.example.com/my-group/my-project/-/merge_requests/1`
`work_in_progress`	Boolean	—

APIEntitiesMilestone

Property	Type	Description
`created_at`	String	—
`description`	String	—
`due_date`	String	—
`expired`	Boolean	—
`group_id`	String	—
`id`	Integer (int64)	—
`iid`	Integer (int64)	—
`project_id`	Integer (int64)	—
`start_date`	String	—
`state`	String	—
`title`	String	—
`updated_at`	String	—
`web_url`	String	—

APIEntitiesTaskCompletionStatus

Property	Type	Description
`completed_count`	Integer	Example: `3`
`count`	Integer	Example: `5`

APIEntitiesUserBasic

Property	Type	Description
`avatar_path`	String	Example: `/user/avatar/28/The-Big-Lebowski-400-400.png`
`avatar_url`	String	Example: `https://gravatar.com/avatar/1`
`custom_attributes`	Array of APIEntitiesCustomAttribute	—
`id`	Integer (int64)	Example: `1`
`locked`	Boolean	—
`name`	String	Example: `Administrator`
`public_email`	String	Example: `john@example.com`
`state`	String	Example: `active`
`username`	String	Example: `admin`
`web_url`	String	Example: `https://gitlab.example.com/root`

List all group milestones

Create a group milestone

Retrieve a group milestone

Update a group milestone

Delete a group milestone

List all issues assigned to a single milestone

List all merge requests assigned to a single milestone

List all project milestones

Create a project milestone

Retrieve a project milestone

Update a project milestone

Delete a project milestone

List all issues for a project milestone

List all merge requests for a project milestone

Promote a project milestone to a group milestone

Schemas

APIEntitiesCustomAttribute

APIEntitiesIssuableReferences

APIEntitiesIssuableTimeStats

APIEntitiesIssueBasic

APIEntitiesMergeRequestBasic

APIEntitiesMilestone

APIEntitiesTaskCompletionStatus

APIEntitiesUserBasic

Request trial access

Thank you

Error

Request callback

Thank you

Something went wrong

Book your sessions

Thank you

Error

Request demo

Thank you

Error

Get the PCI SSC Compliance Report

Thank you

Error