Skip to content
forgit api docs

List all project merge requests

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

Lists all project merge requests.

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
id
required
One of:
string

The ID or URL-encoded path of the project.

Query Parameters

Section titled “ Query Parameters ”
author_id
integer
nullable

Returns merge requests created by the given user id. Mutually exclusive with author_username. Combine with scope=all or scope=assigned_to_me.

author_username
string
nullable

Returns merge requests created by the given username. Mutually exclusive with author_id.

assignee_id
One of:
integer
nullable

Returns merge requests assigned to the given user id. None returns unassigned merge requests. Any returns merge requests with an assignee.

assignee_username
Array<string>
nullable

Returns merge requests created by the given username. Mutually exclusive with author_id.

reviewer_username
string
nullable

Returns merge requests which have the user as a reviewer with the given username. None returns merge requests with no reviewers. Any returns merge requests with any reviewer. Mutually exclusive with reviewer_id. Introduced in GitLab 13.8.

labels
Array<string>
nullable

Returns merge requests matching a comma-separated list of labels. None lists all merge requests with no labels. Any lists all merge requests with at least one label. Predefined names are case-insensitive.

milestone
string
nullable

Returns merge requests for a specific milestone. None returns merge requests with no milestone. Any returns merge requests that have an assigned milestone.

my_reaction_emoji
string
nullable

Returns merge requests reacted by the authenticated user by the given emoji. None returns issues not given a reaction. Any returns issues given at least one reaction.

reviewer_id
One of:
integer
nullable

Returns merge requests which have the user as a reviewer with the given user id. None returns merge requests with no reviewers. Any returns merge requests with any reviewer. Mutually exclusive with reviewer_username.

state
string
default: all nullable
Allowed values: opened closed locked merged all

Returns all merge requests or just those that are opened, closed, locked, or merged.

order_by
string
default: created_at nullable
Allowed values: created_at label_priority milestone_due popularity priority title updated_at merged_at

Returns merge requests ordered by created_at, label_priority, milestone_due, popularity, priority, title, updated_at or merged_at fields. Introduced in GitLab 14.8.

sort
string
default: desc nullable
Allowed values: asc desc

Returns merge requests sorted in asc or desc order.

with_labels_details
boolean
nullable

If true, response returns more details for each label in labels field: :name,:color, :description, :description_html, :text_color

with_merge_status_recheck
boolean
nullable

If true, this projection requests (but does not guarantee) that the merge_status field be recalculated asynchronously. Introduced in GitLab 13.0.

created_after
string format: date-time
nullable

Returns merge requests created on or after the given time. Expected in ISO 8601 format.

Example 
2019-03-15T08:00:00Z
created_before
string format: date-time
nullable

Returns merge requests created on or before the given time. Expected in ISO 8601 format.

Example 
2019-03-15T08:00:00Z
updated_after
string format: date-time
nullable

Returns merge requests updated on or after the given time. Expected in ISO 8601 format.

Example 
2019-03-15T08:00:00Z
updated_before
string format: date-time
nullable

Returns merge requests updated on or before the given time. Expected in ISO 8601 format.

Example 
2019-03-15T08:00:00Z
view
string
nullable
Allowed values: simple

If simple, returns the iid, URL, title, description, and basic state of merge request

scope
string
nullable
Allowed values: created-by-me assigned-to-me created_by_me assigned_to_me reviews_for_me all

Returns merge requests for the given scope: created_by_me, assigned_to_me, reviews_for_me or all

source_branch
string
nullable

Returns merge requests with the given source branch

source_project_id
integer
nullable

Returns merge requests with the given source project id

target_branch
string
nullable

Returns merge requests with the given target branch

search
string
nullable

Search merge requests against their title and description.

in
string
nullable

Modify the scope of the search attribute. title, description, or a string joining them with comma.

Example 
title,description
wip
string
nullable
Allowed values: yes no

Deprecated. Use draft instead. Filter merge requests against their wip status. yes to return only draft merge requests, no to return non-draft merge requests.

draft
boolean
nullable

Filter merge requests against their draft status. true to return only draft merge requests, false to return non-draft merge requests.

not

Returns merge requests that do not match the parameters supplied

object
not[author_id]
integer
nullable

<Negated> Returns merge requests created by the given user id. Mutually exclusive with author_username. Combine with scope=all or scope=assigned_to_me.

not[author_username]
string
nullable

<Negated> Returns merge requests created by the given username. Mutually exclusive with author_id.

not[assignee_id]
One of:
integer
nullable

<Negated> Returns merge requests assigned to the given user id. None returns unassigned merge requests. Any returns merge requests with an assignee.

not[assignee_username]
Array<string>
nullable

<Negated> Returns merge requests created by the given username. Mutually exclusive with author_id.

not[reviewer_username]
string
nullable

<Negated> Returns merge requests which have the user as a reviewer with the given username. None returns merge requests with no reviewers. Any returns merge requests with any reviewer. Mutually exclusive with reviewer_id. Introduced in GitLab 13.8.

not[labels]
Array<string>
nullable

<Negated> Returns merge requests matching a comma-separated list of labels. None lists all merge requests with no labels. Any lists all merge requests with at least one label. Predefined names are case-insensitive.

not[milestone]
string
nullable

<Negated> Returns merge requests for a specific milestone. None returns merge requests with no milestone. Any returns merge requests that have an assigned milestone.

not[my_reaction_emoji]
string
nullable

<Negated> Returns merge requests reacted by the authenticated user by the given emoji. None returns issues not given a reaction. Any returns issues given at least one reaction.

not[reviewer_id]
integer
nullable

<Negated> Returns merge requests which have the user as a reviewer with the given user id. None returns merge requests with no reviewers. Any returns merge requests with any reviewer. Mutually exclusive with reviewer_username.

deployed_before
string
nullable

Returns merge requests deployed before the given date/time. Expected in ISO 8601 format.

Example 
2019-03-15T08:00:00Z
deployed_after
string
nullable

Returns merge requests deployed after the given date/time. Expected in ISO 8601 format

Example 
2019-03-15T08:00:00Z
environment
string
nullable

Returns merge requests deployed to the given environment

Example 
2019-03-15T08:00:00Z
merge_user_id
integer
nullable

Returns merge requests which have been merged by the user with the given user id. Mutually exclusive with merge_user_username.

merge_user_username
string
nullable

Returns merge requests which have been merged by the user with the given username. Mutually exclusive with merge_user_id.

approver_ids
One of:
string
nullable

Return merge requests which have specified the users with the given IDs as an individual approver

approved_by_ids
One of:
string
nullable

Return merge requests which have been approved by the specified users with the given IDs

approved_by_usernames
One of:
string
nullable

Return merge requests which have been approved by the specified users with the given usernames

page
integer
default: 1 nullable

Current page number

Example 
1
per_page
integer
default: 20 nullable

Number of items per page

Example 
20
iids
Array<integer>
nullable

Returns the request having the given iid.

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

OK

Media type application/json
object
id
integer format: int64
iid
integer
project_id
integer format: int64
title
string
description
string
state
string
created_at
string format: date-time
updated_at
string format: date-time
merged_by
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
merge_user
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
merged_at
string format: date-time
closed_by
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
closed_at
string format: date-time
title_html
string
description_html
string
target_branch
string
source_branch
string
user_notes_count
integer
upvotes
integer
downvotes
integer
author
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
assignees
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
assignee
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
reviewers
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
source_project_id
integer format: int64
target_project_id
integer format: int64
labels
Array<string>
draft
boolean
imported
boolean
imported_from
string
work_in_progress
boolean
milestone
object
id
integer format: int64
iid
integer format: int64
project_id
integer format: int64
group_id
string
title
string
description
string
state
string
created_at
string
updated_at
string
due_date
string
start_date
string
expired
boolean
web_url
string
merge_when_pipeline_succeeds
boolean
merge_status
string
detailed_merge_status
string
merge_after
string format: date-time
sha
string
merge_commit_sha
string
squash_commit_sha
string
discussion_locked
boolean
should_remove_source_branch
boolean
force_remove_source_branch
boolean
prepared_at
string format: date-time
allow_collaboration
boolean
allow_maintainer_to_push
boolean
reference
string
references
object
short
string
relative
string
full
string
web_url
string
time_stats
object
time_estimate
integer
total_time_spent
integer
human_time_estimate
string
human_total_time_spent
string
squash
boolean
squash_on_merge
boolean
task_completion_status
object
count
integer
completed_count
integer
has_conflicts
boolean
blocking_discussions_resolved
boolean
approvals_before_merge
integer
Example 
{
  "id": 84,
  "iid": 14,
  "project_id": 4,
  "title": "Impedit et ut et dolores vero provident ullam est",
  "description": "Repellendus impedit et vel velit dignissimos.",
  "state": "closed",
  "created_at": "2022-08-17T12:46:35.053Z",
  "updated_at": "2022-11-14T17:22:01.470Z",
  "merged_by": {
    "id": 1,
    "username": "admin",
    "public_email": "john@example.com",
    "name": "Administrator",
    "state": "active",
    "avatar_url": "https://gravatar.com/avatar/1",
    "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
    "custom_attributes": [
      {
        "key": "foo",
        "value": "bar"
      }
    ],
    "web_url": "https://gitlab.example.com/root"
  },
  "merge_user": {
    "id": 1,
    "username": "admin",
    "public_email": "john@example.com",
    "name": "Administrator",
    "state": "active",
    "avatar_url": "https://gravatar.com/avatar/1",
    "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
    "custom_attributes": [
      {
        "key": "foo",
        "value": "bar"
      }
    ],
    "web_url": "https://gitlab.example.com/root"
  },
  "merged_at": "2022-01-31T15:10:45.080Z",
  "closed_by": {
    "id": 1,
    "username": "admin",
    "public_email": "john@example.com",
    "name": "Administrator",
    "state": "active",
    "avatar_url": "https://gravatar.com/avatar/1",
    "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
    "custom_attributes": [
      {
        "key": "foo",
        "value": "bar"
      }
    ],
    "web_url": "https://gitlab.example.com/root"
  },
  "closed_at": "2022-01-31T15:10:45.080Z",
  "author": {
    "id": 1,
    "username": "admin",
    "public_email": "john@example.com",
    "name": "Administrator",
    "state": "active",
    "avatar_url": "https://gravatar.com/avatar/1",
    "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
    "custom_attributes": [
      {
        "key": "foo",
        "value": "bar"
      }
    ],
    "web_url": "https://gitlab.example.com/root"
  },
  "assignees": {
    "id": 1,
    "username": "admin",
    "public_email": "john@example.com",
    "name": "Administrator",
    "state": "active",
    "avatar_url": "https://gravatar.com/avatar/1",
    "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
    "custom_attributes": [
      {
        "key": "foo",
        "value": "bar"
      }
    ],
    "web_url": "https://gitlab.example.com/root"
  },
  "assignee": {
    "id": 1,
    "username": "admin",
    "public_email": "john@example.com",
    "name": "Administrator",
    "state": "active",
    "avatar_url": "https://gravatar.com/avatar/1",
    "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
    "custom_attributes": [
      {
        "key": "foo",
        "value": "bar"
      }
    ],
    "web_url": "https://gitlab.example.com/root"
  },
  "reviewers": {
    "id": 1,
    "username": "admin",
    "public_email": "john@example.com",
    "name": "Administrator",
    "state": "active",
    "avatar_url": "https://gravatar.com/avatar/1",
    "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
    "custom_attributes": [
      {
        "key": "foo",
        "value": "bar"
      }
    ],
    "web_url": "https://gitlab.example.com/root"
  },
  "imported_from": "bitbucket",
  "merge_status": "unchecked",
  "detailed_merge_status": "mergeable",
  "merge_after": "2022-01-31T15:10:45.080Z",
  "sha": "1234abcd",
  "merge_commit_sha": "1234abcd",
  "squash_commit_sha": "1234abcd",
  "prepared_at": "2022-01-31T15:10:45.080Z",
  "reference": "!1",
  "references": {
    "short": "&6",
    "relative": "&6",
    "full": "test&6"
  },
  "web_url": "https://gitlab.example.com/my-group/my-project/-/merge_requests/1",
  "time_stats": {
    "time_estimate": 12600,
    "total_time_spent": 3600,
    "human_time_estimate": "3h 30m",
    "human_total_time_spent": "1h"
  },
  "task_completion_status": {
    "count": 5,
    "completed_count": 3
  },
  "approvals_before_merge": 2
}

400

Section titled “ 400 ”

Bad Request

401

Section titled “ 401 ”

Unauthorized

404

Section titled “ 404 ”

Not found

422

Section titled “ 422 ”

Unprocessable entity