Jobs API

Retry a job

Retries a failed or timed_out job.

curl -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/builds/{build.number}/jobs/{job.id}/retry"
    {
      "id": "b63254c0-3271-4a98-8270-7cfbd6c2f14e",
      "type": "script",
      "name": "scripts/build.sh",
      "agent_query_rules": ["*"],
      "state": "scheduled",
      "web_url": "https://buildkite.com/my-great-org/my-pipeline/builds/1#b63254c0-3271-4a98-8270-7cfbd6c2f14e",
      "log_url": "https://api.buildkite.com/v2/organizations/my-great-org/pipelines/my-pipeline/builds/1/jobs/b63254c0-3271-4a98-8270-7cfbd6c2f14e/log",
      "raw_log_url": "https://api.buildkite.com/v2/organizations/my-great-org/pipelines/my-pipeline/builds/1/jobs/b63254c0-3271-4a98-8270-7cfbd6c2f14e/log.txt",
      "command": "scripts/build.sh",
      "exit_status": 0,
      "artifact_paths": "",
      "agent": null,
      "created_at": "2015-05-09T21:05:59.874Z",
      "scheduled_at": "2015-05-09T21:05:59.874Z",
      "started_at": null,
      "finished_at": null
    }

Required scope: write_builds

Success response: 200 OK

Error responses:

400 Bad Request{ "message": "Only failed or timed out jobs can be retried" }

Unblock a job

Unblocks a build’s "Block pipeline" job. The job’s unblockable property indicates whether it is able to be unblocked, and the unblock_url property points to this endpoint.

curl -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/builds/{build.number}/jobs/{job.id}/unblock"  \
  -d '{
    "fields": {
      "name": "Liam Neeson",
      "email": "liam@evilbatmanvillans.com",
    }
  }'
{
  "id": "ded35de2-7de0-4da8-8daa-b4ce0b7f1064",
  "type": "manual",
  "label": "Deploy",
  "state": "unblocked",
  "web_url": null,
  "unblocked_by": {
    "id": "cfbb422f-2e4a-41b5-86f0-59e813b3d6e2",
    "name": "Liam Neeson",
    "email": "liam@evilbatmanvillans.com",
    "avatar_url": "https://www.gravatar.com/avatar/e14f55d3f939977cecbf51b64ff6f861",
    "created_at": "2015-05-09T21:05:59.874Z"
  },
  "unblockable": false
}

Optional request body properties:

unblockerThe user id of the person activating the job.
Default value: the user making the API request.
fieldsThe values for the block step’s fields.

Example: {"release-name": "Flying Dolpin"}

Required scope: write_builds

Success response: 200 OK

Error responses:

400 Bad Request{ "message": "This job type cannot be unblocked" }
422 Unprocessable Entity{ "message": "Unblocker is not a valid user id for this organization"}

Get a job’s log output

curl "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/builds/{build.number}/jobs/{job.id}/log"
{
  "url": "https://api.buildkite.com/v2/organizations/my-great-org/pipelines/my-pipeline/builds/1/jobs/b63254c0-3271-4a98-8270-7cfbd6c2f14e/log",
  "content": "This is the job's log output",
  "size": 28
}

Required scope: read_build_logs

Success response: 200 OK

Alternative formats (via Accept header or file extension):

text/plain.txtThe job’s raw log content
text/html.htmlThe job’s log content as rendered by Terminal

Get a job's environment variables

curl "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/builds/{build.number}/jobs/{job.id}/env"
{
  "env": {
    "CI": "true",
    "BUILDKITE": "true",
    "BUILDKITE_TAG": "",
    "BUILDKITE_REPO": "git@github.com:my-great-org/my-repo.git",
    "BUILDKITE_BRANCH": "master",
    "BUILDKITE_COMMIT": "a65572555600c07c7ee79a2bd909220e1ca5485b",
    "BUILDKITE_JOB_ID": "bde076a8-bc2c-4fda-9652-10220a56d638",
    "BUILDKITE_COMMAND": "buildkite-agent pipeline upload",
    "BUILDKITE_MESSAGE": ":llama:",
    "BUILDKITE_BUILD_ID": "c4e312cb-e734-4f0a-a5bd-1cac2535c57e",
    "BUILDKITE_BUILD_URL": "https://buildkite.com/my-great-org/my-pipeline/builds/15",
    "BUILDKITE_AGENT_NAME": "ci-1",
    "BUILDKITE_COMMAND": "buildkite-agent pipeline upload",
    "BUILDKITE_BUILD_NUMBER": "15",
    "BUILDKITE_ORGANIZATION_SLUG": "my-great-org",
    "BUILDKITE_PIPELINE_SLUG": "my-pipeline",
    "BUILDKITE_PULL_REQUEST": "false",
    "BUILDKITE_BUILD_CREATOR": "Keith Pitt",
    "BUILDKITE_REPO_SSH_HOST": "github.com",
    "BUILDKITE_ARTIFACT_PATHS": "",
    "BUILDKITE_PIPELINE_PROVIDER": "github",
    "BUILDKITE_BUILD_CREATOR_EMAIL": "keith@buildkite.com",
    "BUILDKITE_AGENT_META_DATA_LOCAL": "true"
  }
}

Required scope: read_job_env

Success response: 200 OK

Alternative formats (via Accept header or file extension):

text/plain.txtThe job’s environment in a KEY=VALUE format suitable for parsing by tools such as dotenv