We've recently updated the navigation
You can find Pipelines and Test Analytics in their own sections in the new horizontal menu bar at the top of the page.
Agents API
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 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" } |
---|