Agents API
On this page:
List agents
Returns a paginated list of an organization’s agents.
curl "https://api.buildkite.com/v2/organizations/{org.slug}/agents"
[
{
"id": "0b461f65-e7be-4c80-888a-ef11d81fd971",
"url": "https://api.buildkite.com/v2/organizations/my-great-org/agents/my-agent",
"web_url": "https://buildkite.com/organizations/buildkite/my-great-org/agents/0b461f65-e7be-4c80-888a-ef11d81fd971",
"name": "my-agent",
"connection_state": "connected",
"hostname": "some.server",
"ip_address": "144.132.19.12",
"user_agent": "buildkite-agent/2.1.0 (linux; amd64)",
"version": "2.1.0",
"creator": {
"id": "2eba97bc-7cc7-427f-8feb-1008c72aa1d8",
"name": "Keith Pitt",
"email": "me@keithpitt.com",
"avatar_url": "https://www.gravatar.com/avatar/e14f55d3f939977cecbf51b64ff6f861",
"created_at": "2015-05-09T21:05:59.874Z"
},
"created_at": "2014-02-24T22:33:45.263Z",
"job": {
"id": "cd164055-9649-452b-8d8e-28fe67370a1e",
"type": "script",
"name": "rspec",
"agent_query_rules": ["*"],
"state": "passed",
"build_url": "https://api.buildkite.com/v2/organizations/my-great-org/pipelines/sleeper/builds/50",
"web_url": "https://buildkite.com/my-great-org/sleeper/builds/50#cd164055-9649-452b-8d8e-28fe67370a1e",
"log_url": "https://api.buildkite.com/v2/organizations/my-great-org/pipelines/sleeper/builds/50/jobs/cd164055-9649-452b-8d8e-28fe67370a1e/log",
"raw_log_url": "https://api.buildkite.com/v2/organizations/my-great-org/pipelines/sleeper/builds/50/jobs/cd164055-9649-452b-8d8e-28fe67370a1e/log.txt",
"artifacts_url": "https://api.buildkite.com/v2/organizations/my-great-org/pipelines/sleeper/builds/50/jobs/cd164055-9649-452b-8d8e-28fe67370a1e/artifacts",
"script_path": "sleep 1",
"command": "sleep 1",
"exit_status": 0,
"artifact_paths": "*",
"agent": null,
"created_at": "2015-07-30T12:58:22.942Z",
"scheduled_at": "2015-07-30T12:58:22.935Z",
"started_at": "2015-07-30T12:58:34.000Z",
"finished_at": "2015-07-30T12:58:37.000Z"
},
"last_job_finished_at": null,
"priority": null,
"meta_data": ["key1=val1","key2=val2"]
}
]
Optional query string parameters:
name | Filters the results by the given agent name Example: |
|---|---|
hostname | Filters the results by the given hostname Example: |
version | Filters the results by the given exact version number Example: |
Required scope: read_agents
Success response: 200 OK
Get an agent
curl "https://api.buildkite.com/v2/organizations/{org.slug}/agents/{id}"
{
"id": "0b461f65-e7be-4c80-888a-ef11d81fd971",
"url": "https://api.buildkite.com/v2/organizations/my-great-org/agents/my-agent",
"web_url": "https://buildkite.com/organizations/buildkite/my-great-org/agents/0b461f65-e7be-4c80-888a-ef11d81fd971",
"name": "my-agent",
"connection_state": "connected",
"hostname": "some.server",
"ip_address": "144.132.19.12",
"user_agent": "buildkite-agent/2.1.0 (linux; amd64)",
"version": "2.1.0",
"creator": {
"id": "2eba97bc-7cc7-427f-8feb-1008c72aa1d8",
"name": "Keith Pitt",
"email": "me@keithpitt.com",
"avatar_url": "https://www.gravatar.com/avatar/e14f55d3f939977cecbf51b64ff6f861",
"created_at": "2015-05-09T21:05:59.874Z"
},
"created_at": "2015-05-09T21:05:59.874Z",
"job": {
"id": "cd164055-9649-452b-8d8e-28fe67370a1e",
"type": "script",
"name": "rspec",
"agent_query_rules": ["*"],
"state": "passed",
"build_url": "https://api.buildkite.com/v2/organizations/my-great-org/pipelines/sleeper/builds/50",
"web_url": "https://buildkite.com/my-great-org/sleeper/builds/50#cd164055-9649-452b-8d8e-28fe67370a1e",
"log_url": "https://api.buildkite.com/v2/organizations/my-great-org/pipelines/sleeper/builds/50/jobs/cd164055-9649-452b-8d8e-28fe67370a1e/log",
"raw_log_url": "https://api.buildkite.com/v2/organizations/my-great-org/pipelines/sleeper/builds/50/jobs/cd164055-9649-452b-8d8e-28fe67370a1e/log.txt",
"artifacts_url": "https://api.buildkite.com/v2/organizations/my-great-org/pipelines/sleeper/builds/50/jobs/cd164055-9649-452b-8d8e-28fe67370a1e/artifacts",
"script_path": "sleep 1",
"command": "sleep 1",
"exit_status": 0,
"artifact_paths": "*",
"agent": null,
"created_at": "2015-07-30T12:58:22.942Z",
"scheduled_at": "2015-07-30T12:58:22.935Z",
"started_at": "2015-07-30T12:58:34.000Z",
"finished_at": "2015-07-30T12:58:37.000Z"
},
"last_job_finished_at": null,
"priority": null,
"meta_data": ["key1=val1","key2=val2"]
}
Required scope: read_agents
Success response: 200 OK
Stop an agent
Instruct an agent to stop accepting new build jobs and shut itself down.
curl -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/agents/{id}/stop" \
-d '{
"force": true
}'
Optional request body properties:
force | If the agent is currently processing a job, the job and the build will be cancelled. Default: |
|---|
Required scope: write_agents
Success response: 204 No Content
Error responses:
400 Bad Request | { "message": "Can only stop connected agents" } |
|---|