Jobs API

Retry a job

Retries a failed OR timed_out OR a job whose step has the manual retry after passing attribute set to true (that is, permit_on_passed: true). You can only retry each job.id once. To retry a "second time" use the new job.id returned in the first retry query.

curl -H "Authorization: Bearer $TOKEN" \
  -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",
      "graphql_id": "Sm9iLS0tMTQ4YWQ0MzgtM2E2My00YWIxLWIzMjItNzIxM2Y3YzJhMWFi",
      "type": "script",
      "name": "📦",
      "step_key": "package",
      "agent_query_rules": ["*"],
      "state": "scheduled",
      "build_url": "https://buildkite.com/my-great-org/my-pipeline/builds/1",
      "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",
      "artifacts_url": "",
      "command": "scripts/build.sh",
      "soft_failed": false,
      "exit_status": 0,
      "artifact_paths": "",
      "agent": null,
      "created_at": "2015-05-09T21:05:59.874Z",
      "scheduled_at": "2015-05-09T21:05:59.874Z",
      "runnable_at": null,
      "started_at": null,
      "finished_at": null,
      "retried": false,
      "retried_in_job_id": null,
      "retries_count": 1,
      "retry_type": null,
      "parallel_group_index": null,
      "parallel_group_total": null
    }

Required scope: write_builds

Success response: 200 OK

Error responses:

`400 Bad Request`	`{ "message": "Only failed, timed out or canceled 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 -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/builds/{build.number}/jobs/{job.id}/unblock"  \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "name": "Liam Neeson",
      "email": "liam@evilbatmanvillans.com"
    }
  }'

{
  "id": "ded35de2-7de0-4da8-8daa-b4ce0b7f1064",
  "graphql_id": "Sm9iLS0tZGM5YTg5MmQtM2I5Ny00MzgyLWEzYzItNWJhZmU5M2RlZWI1",
  "type": "manual",
  "label": "Deploy",
  "state": "unblocked",
  "web_url": null,
  "unblocked_by": {
    "id": "cfbb422f-2e4a-41b5-86f0-59e813b3d6e2",
    "graphql_id": "VXNlci0tLTBmYTQzYjY2LWI5N2YtNDc0Yi04Y2YxLWIxMzQ5NWIxYjRjMQ==",
    "name": "Liam Neeson",
    "email": "liam@evilbatmanvillans.com",
    "avatar_url": "https://www.gravatar.com/avatar/e14f55d3f939977cecbf51b64ff6f861",
    "created_at": "2015-05-09T21:05:59.874Z"
  },
  "unblocked_at": "2015-05-09T21:06:10.264Z",
  "unblockable": false,
  "unblock_url": "https://buildkite.com/my-great-org/my-pipeline/builds/1#ded35de2-7de0-4da8-8daa-b4ce0b7f1064"
}

Optional request body properties:

`unblocker`	The user id of the person activating the job. Default value: the user making the API request.
`fields`	The 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 -H "Authorization: Bearer $TOKEN" \
  -X GET "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,
  "header_times": [1563337899810051000,1563337899811015000,1563337905336878000,1563337906589603000,156333791038291900]
}

Required scope: read_build_logs

Success response: 200 OK

Alternative formats (using Accept header or file extension):

`text/plain`	`.txt`	The job's raw log content
`text/html`	`.html`	The job's log content as rendered by Terminal

Delete a job's log output

curl -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/builds/{build.number}/jobs/{job.id}/log"

Required scope: write_build_logs

Success response: 204 No Content

Get a job's environment variables

curl -H "Authorization: Bearer $TOKEN" \
  -X GET "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": "main",
    "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 (using Accept header or file extension):

`text/plain`	`.txt`	The job's environment in a `KEY=VALUE` format suitable for parsing by tools such as dotenv