# Pipeline schedules API

The pipeline schedules API endpoint allows you to manage [scheduled builds](/docs/pipelines/configure/workflows/scheduled-builds) for a pipeline. Pipeline schedules automatically create builds at specified intervals, such as nightly builds or hourly integration tests.

## Pipeline schedule data model



| `id` | UUID of the pipeline schedule. |
| --- | --- |
| `graphql_id` | [GraphQL ID](/docs/apis/graphql-api#graphql-ids) of the pipeline schedule. |
| `url` | Canonical API URL of the pipeline schedule. |
| `label` | Label describing the pipeline schedule. |
| `cronline` | The interval used to trigger builds. Either a [predefined interval](/docs/pipelines/configure/workflows/scheduled-builds#schedule-intervals) (such as `@hourly` or `@daily`) or a [crontab time syntax](/docs/pipelines/configure/workflows/scheduled-builds#schedule-intervals-crontab-time-syntax) string. |
| `message` | Message used for the builds created by the pipeline schedule. |
| `commit` | Commit used for the builds created by the pipeline schedule. Defaults to `HEAD`. |
| `branch` | Branch used for the builds created by the pipeline schedule. Defaults to the pipeline's default branch. |
| `env` | JSON object of environment variables to set on the builds created by the pipeline schedule. |
| `enabled` | Whether the pipeline schedule is enabled. |
| `next_build_at` | When the next build will be created. |
| `failed_message` | Failure message from the most recent failed attempt to create a build, or `null` if the most recent attempt succeeded. |
| `failed_at` | When the most recent failed attempt to create a build occurred, or `null` if the most recent attempt succeeded. |
| `created_at` | When the pipeline schedule was created. |
| `created_by` | [User](/docs/apis/rest-api/user) who created the pipeline schedule. |
| `pipeline` | Reference to the parent pipeline, including its `id`, `slug`, and API `url`. |



## List pipeline schedules

Returns a [paginated list](/docs/rest-api#pagination) of the schedules for a pipeline, with the most recently created first.

_Example request:_

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/schedules"
```

_Example response:_

```json
[
  {
    "id": "b3a1e9f2-7c4d-4f1a-9e6c-2d8a5f7b1c3d",
    "graphql_id": "UGlwZWxpbmVTY2hlZHVsZS0tLWIzYTFlOWYyLTdjNGQtNGYxYS05ZTZjLTJkOGE1ZjdiMWMzZA==",
    "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/schedules/b3a1e9f2-7c4d-4f1a-9e6c-2d8a5f7b1c3d",
    "label": "Nightly build",
    "cronline": "@daily",
    "message": "Nightly scheduled build",
    "commit": "HEAD",
    "branch": "main",
    "env": {
      "DEPLOY_ENV": "staging"
    },
    "enabled": true,
    "next_build_at": "2024-01-02T00:00:00.000Z",
    "failed_message": null,
    "failed_at": null,
    "created_at": "2024-01-01T12:00:00.000Z",
    "created_by": {
      "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
      "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
      "name": "Sam Kim",
      "email": "sam@example.com",
      "avatar_url": "https://www.gravatar.com/avatar/example",
      "created_at": "2013-05-03T04:17:55.867Z"
    },
    "pipeline": {
      "id": "9d1d1e9c-5e8f-4f9a-9b0c-1a2b3c4d5e6f",
      "slug": "my-pipeline",
      "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline"
    }
  }
]
```

Required scope: `read_pipelines`

Success response: `200 OK`

## Get a pipeline schedule

Returns the details for a single pipeline schedule.

_Example request:_

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/schedules/{id}"
```

_Example response:_

```json
{
  "id": "b3a1e9f2-7c4d-4f1a-9e6c-2d8a5f7b1c3d",
  "graphql_id": "UGlwZWxpbmVTY2hlZHVsZS0tLWIzYTFlOWYyLTdjNGQtNGYxYS05ZTZjLTJkOGE1ZjdiMWMzZA==",
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/schedules/b3a1e9f2-7c4d-4f1a-9e6c-2d8a5f7b1c3d",
  "label": "Nightly build",
  "cronline": "@daily",
  "message": "Nightly scheduled build",
  "commit": "HEAD",
  "branch": "main",
  "env": {
    "DEPLOY_ENV": "staging"
  },
  "enabled": true,
  "next_build_at": "2024-01-02T00:00:00.000Z",
  "failed_message": null,
  "failed_at": null,
  "created_at": "2024-01-01T12:00:00.000Z",
  "created_by": {
    "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
    "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2013-05-03T04:17:55.867Z"
  },
  "pipeline": {
    "id": "9d1d1e9c-5e8f-4f9a-9b0c-1a2b3c4d5e6f",
    "slug": "my-pipeline",
    "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline"
  }
}
```

Required scope: `read_pipelines`

Success response: `200 OK`

## Create a pipeline schedule

Creates a new pipeline schedule.

_Example request:_

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/schedules" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Nightly build",
    "cronline": "@daily",
    "message": "Nightly scheduled build",
    "commit": "HEAD",
    "branch": "main",
    "env": {
      "DEPLOY_ENV": "staging"
    },
    "enabled": true
  }'
```

_Example response:_

```json
{
  "id": "b3a1e9f2-7c4d-4f1a-9e6c-2d8a5f7b1c3d",
  "graphql_id": "UGlwZWxpbmVTY2hlZHVsZS0tLWIzYTFlOWYyLTdjNGQtNGYxYS05ZTZjLTJkOGE1ZjdiMWMzZA==",
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/schedules/b3a1e9f2-7c4d-4f1a-9e6c-2d8a5f7b1c3d",
  "label": "Nightly build",
  "cronline": "@daily",
  "message": "Nightly scheduled build",
  "commit": "HEAD",
  "branch": "main",
  "env": {
    "DEPLOY_ENV": "staging"
  },
  "enabled": true,
  "next_build_at": "2024-01-02T00:00:00.000Z",
  "failed_message": null,
  "failed_at": null,
  "created_at": "2024-01-01T12:00:00.000Z",
  "created_by": {
    "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
    "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2013-05-03T04:17:55.867Z"
  },
  "pipeline": {
    "id": "9d1d1e9c-5e8f-4f9a-9b0c-1a2b3c4d5e6f",
    "slug": "my-pipeline",
    "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline"
  }
}
```

Required [request body properties](/docs/api#request-body-properties):



| `cronline` | The interval used to trigger builds. Either a [predefined interval](/docs/pipelines/configure/workflows/scheduled-builds#schedule-intervals) or a [crontab time syntax](/docs/pipelines/configure/workflows/scheduled-builds#schedule-intervals-crontab-time-syntax) string. _Example:_ `"@daily"` |
| --- | --- |



Optional [request body properties](/docs/api#request-body-properties):



| `label` | Label describing the pipeline schedule. _Example:_ `"Nightly build"` |
| --- | --- |
| `message` | Message used for the builds created by the pipeline schedule. _Example:_ `"Nightly scheduled build"` |
| `commit` | Commit used for the builds created by the pipeline schedule. _Default:_ `"HEAD"` |
| `branch` | Branch used for the builds created by the pipeline schedule. _Default:_ the pipeline's default branch |
| `env` | JSON object of environment variables to set on the builds created by the pipeline schedule. _Example:_ `{ "DEPLOY_ENV": "staging" }` |
| `enabled` | Whether the pipeline schedule is enabled. _Default:_ `true` |



Required scope: `write_pipelines`

Success response: `201 Created`

Error responses:



| `422 Unprocessable Entity` | `{ "message": "Validation failed: Reason for failure" }` |
| --- | --- |



## Update a pipeline schedule

Updates the pipeline schedule.

_Example request:_

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/schedules/{id}" \
  -H "Content-Type: application/json" \
  -d '{
    "cronline": "@hourly",
    "enabled": false
  }'
```

_Example response:_

```json
{
  "id": "b3a1e9f2-7c4d-4f1a-9e6c-2d8a5f7b1c3d",
  "graphql_id": "UGlwZWxpbmVTY2hlZHVsZS0tLWIzYTFlOWYyLTdjNGQtNGYxYS05ZTZjLTJkOGE1ZjdiMWMzZA==",
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/schedules/b3a1e9f2-7c4d-4f1a-9e6c-2d8a5f7b1c3d",
  "label": "Nightly build",
  "cronline": "@hourly",
  "message": "Nightly scheduled build",
  "commit": "HEAD",
  "branch": "main",
  "env": {
    "DEPLOY_ENV": "staging"
  },
  "enabled": false,
  "next_build_at": null,
  "failed_message": null,
  "failed_at": null,
  "created_at": "2024-01-01T12:00:00.000Z",
  "created_by": {
    "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
    "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2013-05-03T04:17:55.867Z"
  },
  "pipeline": {
    "id": "9d1d1e9c-5e8f-4f9a-9b0c-1a2b3c4d5e6f",
    "slug": "my-pipeline",
    "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline"
  }
}
```

Optional [request body properties](/docs/api#request-body-properties):



| `label` | Label describing the pipeline schedule. _Example:_ `"Nightly build"` |
| --- | --- |
| `cronline` | The interval used to trigger builds. _Example:_ `"@hourly"` |
| `message` | Message used for the builds created by the pipeline schedule. _Example:_ `"Nightly scheduled build"` |
| `commit` | Commit used for the builds created by the pipeline schedule. _Example:_ `"HEAD"` |
| `branch` | Branch used for the builds created by the pipeline schedule. _Example:_ `"main"` |
| `env` | JSON object of environment variables to set on the builds created by the pipeline schedule. _Example:_ `{ "DEPLOY_ENV": "staging" }` |
| `enabled` | Whether the pipeline schedule is enabled. Re-enabling a previously failed schedule clears its `failed_message` and `failed_at` values. _Example:_ `true` |



Required scope: `write_pipelines`

Success response: `200 OK`

Error responses:



| `422 Unprocessable Entity` | `{ "message": "Validation failed: Reason for failure" }` |
| --- | --- |



## Delete a pipeline schedule

Deletes a pipeline schedule.

_Example request:_

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/schedules/{id}"
```

Required scope: `write_pipelines`

Success response: `204 No Content`