2020-08-04 06:10:16 +00:00
---
stage: Verify
group: Continuous Integration
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/#designated-technical-writers
---
2016-08-17 13:23:58 +00:00
# Pipelines API
2020-07-17 18:09:20 +00:00
## Single Pipeline Requests
2020-07-25 00:09:23 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36494) in GitLab 13.3.
2020-07-17 18:09:20 +00:00
Endpoints that request information about a single pipeline return data for any pipeline.
2020-07-25 00:09:23 +00:00
Before 13.3, requests for [child pipelines ](../ci/parent_child_pipelines.md ) returned
2020-07-17 18:09:20 +00:00
a 404 error.
2020-05-19 06:08:03 +00:00
## Pipelines pagination
By default, `GET` requests return 20 results at a time because the API results
are paginated.
Read more on [pagination ](README.md#pagination ).
2016-08-17 13:23:58 +00:00
## List project pipelines
2020-03-31 03:07:51 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5837) in GitLab 8.11
2016-08-17 13:23:58 +00:00
2020-02-28 00:09:08 +00:00
```plaintext
2016-08-17 13:23:58 +00:00
GET /projects/:id/pipelines
```
| Attribute | Type | Required | Description |
|-----------|---------|----------|---------------------|
2017-04-08 09:21:11 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2017-04-05 11:48:59 +00:00
| `scope` | string | no | The scope of pipelines, one of: `running` , `pending` , `finished` , `branches` , `tags` |
2020-08-09 21:10:01 +00:00
| `status` | string | no | The status of pipelines, one of: `created` , `waiting_for_resource` , `preparing` , `pending` , `running` , `success` , `failed` , `canceled` , `skipped` , `manual` , `scheduled` |
2017-02-28 12:24:49 +00:00
| `ref` | string | no | The ref of pipelines |
2020-03-26 03:07:43 +00:00
| `sha` | string | no | The SHA of pipelines |
2017-04-27 13:09:18 +00:00
| `yaml_errors` | boolean | no | Returns pipelines with invalid configurations |
2017-04-05 11:48:59 +00:00
| `name` | string | no | The name of the user who triggered pipelines |
| `username` | string | no | The username of the user who triggered pipelines |
2019-12-06 18:07:44 +00:00
| `updated_after` | datetime | no | Return pipelines updated after the specified date. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ |
| `updated_before` | datetime | no | Return pipelines updated before the specified date. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ |
2019-11-22 18:06:00 +00:00
| `order_by` | string | no | Order pipelines by `id` , `status` , `ref` , `updated_at` or `user_id` (default: `id` ) |
2017-04-27 13:09:18 +00:00
| `sort` | string | no | Sort pipelines in `asc` or `desc` order (default: `desc` ) |
2016-08-17 13:23:58 +00:00
2020-02-28 00:09:08 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/pipelines"
2016-08-17 13:23:58 +00:00
```
Example of response
```json
[
{
"id": 47,
"status": "pending",
"ref": "new-pipeline",
2018-07-18 21:57:08 +00:00
"sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
2019-10-04 18:05:55 +00:00
"web_url": "https://example.com/foo/bar/pipelines/47",
"created_at": "2016-08-11T11:28:34.085Z",
"updated_at": "2016-08-11T11:32:35.169Z",
2016-08-17 13:23:58 +00:00
},
{
"id": 48,
"status": "pending",
"ref": "new-pipeline",
2018-07-18 21:57:08 +00:00
"sha": "eb94b618fb5865b26e80fdd8ae531b7a63ad851a",
2019-10-04 18:05:55 +00:00
"web_url": "https://example.com/foo/bar/pipelines/48",
"created_at": "2016-08-12T10:06:04.561Z",
"updated_at": "2016-08-12T10:09:56.223Z",
2016-08-17 13:23:58 +00:00
}
]
```
## Get a single pipeline
2020-03-31 03:07:51 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5837) in GitLab 8.11
2016-08-17 13:23:58 +00:00
2020-02-28 00:09:08 +00:00
```plaintext
2016-08-17 13:23:58 +00:00
GET /projects/:id/pipelines/:pipeline_id
```
| Attribute | Type | Required | Description |
|------------|---------|----------|---------------------|
2017-04-08 09:21:11 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2016-08-17 13:23:58 +00:00
| `pipeline_id` | integer | yes | The ID of a pipeline |
2020-02-28 00:09:08 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/pipelines/46"
2016-08-17 13:23:58 +00:00
```
Example of response
```json
{
"id": 46,
"status": "success",
"ref": "master",
"sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
"before_sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
"tag": false,
"yaml_errors": null,
"user": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80& d=identicon",
2016-10-13 11:24:09 +00:00
"web_url": "http://localhost:3000/root"
2016-08-17 13:23:58 +00:00
},
"created_at": "2016-08-11T11:28:34.085Z",
"updated_at": "2016-08-11T11:32:35.169Z",
"started_at": null,
"finished_at": "2016-08-11T11:32:35.145Z",
"committed_at": null,
2016-11-25 16:38:51 +00:00
"duration": null,
2018-07-18 21:57:08 +00:00
"coverage": "30.0",
"web_url": "https://example.com/foo/bar/pipelines/46"
2016-08-17 13:23:58 +00:00
}
```
2019-04-09 14:53:44 +00:00
### Get variables of a pipeline
2020-02-28 00:09:08 +00:00
```plaintext
2019-04-09 14:53:44 +00:00
GET /projects/:id/pipelines/:pipeline_id/variables
```
| Attribute | Type | Required | Description |
|------------|---------|----------|---------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
| `pipeline_id` | integer | yes | The ID of a pipeline |
2020-02-28 00:09:08 +00:00
```shell
2019-04-09 14:53:44 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/pipelines/46/variables"
```
Example of response
```json
[
{
"key": "RUN_NIGHTLY_BUILD",
2019-05-06 13:11:42 +00:00
"variable_type": "env_var",
2019-04-09 14:53:44 +00:00
"value": "true"
},
{
"key": "foo",
"value": "bar"
}
]
```
2020-05-11 12:10:28 +00:00
### Get a pipeline's test report
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202525) in GitLab 13.0.
2020-08-21 21:10:01 +00:00
NOTE: **Note:**
This API route is part of the [Unit test report ](../ci/unit_test_reports.md ) feature.
2020-05-11 12:10:28 +00:00
```plaintext
GET /projects/:id/pipelines/:pipeline_id/test_report
```
| Attribute | Type | Required | Description |
|------------|---------|----------|---------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
| `pipeline_id` | integer | yes | The ID of a pipeline |
Sample request:
```shell
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/pipelines/46/test_report"
```
Sample response:
```json
{
"total_time": 5,
"total_count": 1,
"success_count": 1,
"failed_count": 0,
"skipped_count": 0,
"error_count": 0,
"test_suites": [
{
"name": "Secure",
"total_time": 5,
"total_count": 1,
"success_count": 1,
"failed_count": 0,
"skipped_count": 0,
"error_count": 0,
"test_cases": [
{
"status": "success",
"name": "Security Reports can create an auto-remediation MR",
"classname": "vulnerability_management_spec",
"execution_time": 5,
"system_output": null,
"stack_trace": null
}
]
}
]
}
```
2016-10-31 20:38:24 +00:00
## Create a new pipeline
2020-03-31 03:07:51 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7209) in GitLab 8.14
2016-10-31 20:38:24 +00:00
2020-02-28 00:09:08 +00:00
```plaintext
2016-10-31 20:38:24 +00:00
POST /projects/:id/pipeline
```
2019-07-04 22:46:12 +00:00
| Attribute | Type | Required | Description |
|-------------|---------|----------|---------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
| `ref` | string | yes | Reference to commit |
2020-07-28 18:09:36 +00:00
| `variables` | array | no | An array containing the variables available in the pipeline, matching the structure `[{ 'key': 'UPLOAD_TO_S3', 'variable_type': 'file', 'value': 'true' }]` |
2016-10-31 20:38:24 +00:00
2020-02-28 00:09:08 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/pipeline?ref=master"
2016-10-31 20:38:24 +00:00
```
Example of response
```json
{
"id": 61,
"sha": "384c444e840a515b23f21915ee5766b87068a70d",
"ref": "master",
"status": "pending",
"before_sha": "0000000000000000000000000000000000000000",
"tag": false,
"yaml_errors": null,
"user": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80& d=identicon",
"web_url": "http://localhost:3000/root"
},
"created_at": "2016-11-04T09:36:13.747Z",
"updated_at": "2016-11-04T09:36:13.977Z",
"started_at": null,
"finished_at": null,
"committed_at": null,
2016-11-25 16:38:51 +00:00
"duration": null,
2018-07-18 21:57:08 +00:00
"coverage": null,
"web_url": "https://example.com/foo/bar/pipelines/61"
2016-10-31 20:38:24 +00:00
}
```
2017-03-06 09:24:03 +00:00
## Retry jobs in a pipeline
2016-08-17 13:23:58 +00:00
2020-03-31 03:07:51 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5837) in GitLab 8.11
2016-08-17 13:23:58 +00:00
2020-02-28 00:09:08 +00:00
```plaintext
2016-08-17 13:23:58 +00:00
POST /projects/:id/pipelines/:pipeline_id/retry
```
| Attribute | Type | Required | Description |
|------------|---------|----------|---------------------|
2017-04-08 09:21:11 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2016-08-17 13:23:58 +00:00
| `pipeline_id` | integer | yes | The ID of a pipeline |
2020-02-28 00:09:08 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/pipelines/46/retry"
2016-08-17 13:23:58 +00:00
```
Response:
```json
{
"id": 46,
"status": "pending",
"ref": "master",
"sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
"before_sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
"tag": false,
"yaml_errors": null,
"user": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80& d=identicon",
2016-10-13 11:24:09 +00:00
"web_url": "http://localhost:3000/root"
2016-08-17 13:23:58 +00:00
},
"created_at": "2016-08-11T11:28:34.085Z",
"updated_at": "2016-08-11T11:32:35.169Z",
"started_at": null,
"finished_at": "2016-08-11T11:32:35.145Z",
"committed_at": null,
2016-11-25 16:38:51 +00:00
"duration": null,
2018-07-18 21:57:08 +00:00
"coverage": null,
"web_url": "https://example.com/foo/bar/pipelines/46"
2016-08-17 13:23:58 +00:00
}
```
2020-05-04 03:09:50 +00:00
## Cancel a pipeline's jobs
2016-08-17 13:23:58 +00:00
2020-03-31 03:07:51 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5837) in GitLab 8.11
2016-08-17 13:23:58 +00:00
2020-02-28 00:09:08 +00:00
```plaintext
2016-08-17 13:23:58 +00:00
POST /projects/:id/pipelines/:pipeline_id/cancel
```
| Attribute | Type | Required | Description |
|------------|---------|----------|---------------------|
2017-04-08 09:21:11 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2016-08-17 13:23:58 +00:00
| `pipeline_id` | integer | yes | The ID of a pipeline |
2020-02-28 00:09:08 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/pipelines/46/cancel"
2016-08-17 13:23:58 +00:00
```
Response:
```json
{
"id": 46,
"status": "canceled",
"ref": "master",
"sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
"before_sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
"tag": false,
"yaml_errors": null,
"user": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80& d=identicon",
2016-10-13 11:24:09 +00:00
"web_url": "http://localhost:3000/root"
2016-08-17 13:23:58 +00:00
},
"created_at": "2016-08-11T11:28:34.085Z",
"updated_at": "2016-08-11T11:32:35.169Z",
"started_at": null,
"finished_at": "2016-08-11T11:32:35.145Z",
"committed_at": null,
2016-11-25 16:38:51 +00:00
"duration": null,
2018-07-18 21:57:08 +00:00
"coverage": null,
"web_url": "https://example.com/foo/bar/pipelines/46"
2016-08-17 13:23:58 +00:00
}
```
2018-11-13 12:58:24 +00:00
## Delete a pipeline
2020-02-06 15:09:11 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22988) in GitLab 11.6.
2018-11-13 12:58:24 +00:00
2020-02-28 00:09:08 +00:00
```plaintext
2018-11-13 12:58:24 +00:00
DELETE /projects/:id/pipelines/:pipeline_id
```
| Attribute | Type | Required | Description |
|------------|---------|----------|---------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
| `pipeline_id` | integer | yes | The ID of a pipeline |
2020-02-28 00:09:08 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " --request "DELETE" "https://gitlab.example.com/api/v4/projects/1/pipelines/46"
2018-11-13 12:58:24 +00:00
```