Pipeline schedules API

The pipeline schedules API endpoint allows you to manage 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 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 (such as @hourly or @daily) or a 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 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 of the schedules for a pipeline, with the most recently created first.

Example request:

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

Example response:

[
  {
    "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:

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

Example response:

{
  "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:

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:

{
  "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:

cronline The interval used to trigger builds. Either a predefined interval or a crontab time syntax string.
Example: "@daily"

Optional 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:

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:

{
  "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:

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:

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