2020-06-17 03:08:38 +00:00
---
stage: Verify
2021-05-26 15:10:57 +00:00
group: Pipeline Execution
2020-11-26 06:09:20 +00:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-06-17 03:08:38 +00:00
---
2020-02-20 18:08:51 +00:00
# Merge Trains API **(PREMIUM)**
2020-05-21 06:08:25 +00:00
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36146) in GitLab 12.9.
2021-06-29 18:07:04 +00:00
> - Using this API you can consume [Merge Train](../ci/pipelines/merge_trains.md) entries.
2020-02-20 18:08:51 +00:00
2020-02-20 21:08:48 +00:00
Every API call to merge trains must be authenticated with Developer or higher [permissions ](../user/permissions.md ).
2020-02-20 18:08:51 +00:00
2020-11-18 18:09:08 +00:00
If a user is not a member of a project and the project is private, a `GET` request on that project returns a `404` status code.
2020-02-20 18:08:51 +00:00
2020-11-18 18:09:08 +00:00
If Merge Trains is not available for the project, a `403` status code is returned.
2020-02-20 18:08:51 +00:00
## Merge Trains API pagination
By default, `GET` requests return 20 results at a time because the API results
are paginated.
2021-06-28 15:08:03 +00:00
Read more on [pagination ](index.md#pagination ).
2020-02-20 18:08:51 +00:00
## List Merge Trains for a project
Get all Merge Trains of the requested project:
2022-06-09 03:08:17 +00:00
```plaintext
2020-02-20 18:08:51 +00:00
GET /projects/:id/merge_trains
GET /projects/:id/merge_trains?scope=complete
```
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- |
2021-06-28 15:08:03 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ). |
2020-02-20 18:08:51 +00:00
| `scope` | string | no | Return Merge Trains filtered by the given scope. Available scopes are `active` (to be merged) and `complete` (have been merged). |
| `sort` | string | no | Return Merge Trains sorted in `asc` or `desc` order. Default is `desc` . |
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/merge_trains"
2020-02-20 18:08:51 +00:00
```
Example response:
```json
[
{
"id": 110,
"merge_request": {
"id": 126,
"iid": 59,
"project_id": 20,
"title": "Test MR 1580978354",
"description": "",
"state": "merged",
"created_at": "2020-02-06T08:39:14.883Z",
"updated_at": "2020-02-06T08:40:57.038Z",
"web_url": "http://local.gitlab.test:8181/root/merge-train-race-condition/-/merge_requests/59"
},
"user": {
"id": 1,
"name": "Administrator",
"username": "root",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80& d=identicon",
"web_url": "http://local.gitlab.test:8181/root"
},
"pipeline": {
"id": 246,
"sha": "bcc17a8ffd51be1afe45605e714085df28b80b13",
"ref": "refs/merge-requests/59/train",
"status": "success",
"created_at": "2020-02-06T08:40:42.410Z",
"updated_at": "2020-02-06T08:40:46.912Z",
"web_url": "http://local.gitlab.test:8181/root/merge-train-race-condition/pipelines/246"
},
"created_at": "2020-02-06T08:39:47.217Z",
"updated_at": "2020-02-06T08:40:57.720Z",
"target_branch": "feature-1580973432",
"status": "merged",
"merged_at": "2020-02-06T08:40:57.719Z",
"duration": 70
}
]
```