Agents API
On this page:
List agents
Returns a paginated list of an organization’s agents. The list only includes connected agents - agents in a disconnected state are not returned.
curl "https://api.buildkite.com/v2/organizations/{org.slug}/agents"
[
{
"id": "0b461f65-e7be-4c80-888a-ef11d81fd971",
"graphql_id": "QWdlbnQtLS1mOTBhNzliNC01YjJlLTQzNzEtYjYxZS03OTA4ZDAyNmUyN2E=",
"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",
"graphql_id": "Sm9iLS0tMTQ4YWQ0MzgtM2E2My00YWIxLWIzMjItNzIxM2Y3YzJhMWFi",
"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",
"soft_failed": false,
"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
Returns the details for a single agent, looked up by unique ID. Any valid agents can be returned, including running and disconnected agents.
curl "https://api.buildkite.com/v2/organizations/{org.slug}/agents/{id}"
{
"id": "0b461f65-e7be-4c80-888a-ef11d81fd971",
"graphql_id": "QWdlbnQtLS1mOTBhNzliNC01YjJlLTQzNzEtYjYxZS03OTA4ZDAyNmUyN2E=",
"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",
"graphql_id": "VXNlci0tLThmNzFlOWI1LTczMDEtNDI4ZS1hMjQ1LWUwOWI0YzI0OWRiZg==",
"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",
"graphql_id": "Sm9iLS0tZGM5YTg5MmQtM2I5Ny00MzgyLWEzYzItNWJhZmU5M2RlZWI1",
"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",
"soft_failed": false,
"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
Required permissions
To stop an agent you need either- An Admin user API token with write_agents scope
- Or, if you're using Enterprise Member Permissions, a user token with the Stop Agents permission
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 canceled. Default: |
|---|
Required scope: write_agents
Success response: 204 No Content
Error responses:
400 Bad Request |
{ "message": "Can only stop connected agents" } |
|---|