# 3.5.24. worker

resource type: worker
  Attributes:

    - workerid (integer) – the ID of this worker

    - configured_on[] –

      list of builders on masters this worker is configured on

      - `builderid` (integer)

      - `masterid` (integer)

    - connected_to[] –

      list of masters this worker is attached to

      - `masterid` (integer)

    - name (string) – the name of the worker

    - paused (bool) – the worker is paused if it is connected but doesn’t accept new builds

    - pause_reason? (string) – the reason for pausing the worker, if the worker is paused

    - graceful (bool) – the worker is graceful if it doesn’t accept new builds, and will shutdown when builds are finished

    - workerinfo (object) –

      information about the worker

      The worker information can be any JSON-able object. In practice, it contains the following keys, based on information provided by the worker:

      - `admin` (the admin information)

      - `host` (the name of the host)

      - `access_uri` (the access URI)

      - `version` (the version on the worker)

A worker resource represents a worker to the source code monitored by Buildbot.

The contents of the `connected_to` and `configured_on` attributes are sensitive to the context of the request. If a builder or master is specified in the path, then only the corresponding connections and configurations are included in the result.

## 3.5.24.1. Endpoints

path: /builders/{builderid_or_buildername}/workers
  Path Keys:

    builderid_or_buildername (number|string) – the ID or name of the builder

This path selects all workers configured for a given builder

`GET`
  `returns`

    `collection` of `worker`

path: /builders/{builderid_or_buildername}/workers/{name}
  Path Keys:

    - builderid_or_buildername (number|string) – the ID or name of the builder

    - name (identifier) – the name of the worker

This path selects a worker by name filtered by given builderid

`GET`
  `returns`

    `collection` of `worker`

path: /builders/{builderid_or_buildername}/workers/{workerid}
  Path Keys:

    - builderid_or_buildername (number|string) – the ID or name of the builder

    - workerid (number) – the id of the worker

This path selects a worker by id filtered by given builderid

`GET`
  `returns`

    `collection` of `worker`

POST with method: /builders/{builderid_or_buildername}/workers/{workerid} (method=stop)
  Body keys:

    - method (string) – must be `stop`

    - reason (string) – The reason why the worker was stopped

POST with method: /builders/{builderid_or_buildername}/workers/{workerid} (method=kill)
  Body keys:

    - method (string) – must be `kill`

    - reason (string) – The reason why the worker was stopped

POST with method: /builders/{builderid_or_buildername}/workers/{workerid} (method=pause)
  Body keys:

    - method (string) – must be `pause`

    - reason (string) – The reason why the worker was paused

POST with method: /builders/{builderid_or_buildername}/workers/{workerid} (method=unpause)
  Body keys:

    - method (string) – must be `unpause`

    - reason (string) – The reason why the worker was un-paused

path: /masters/{masterid}/builders/{builderid}/workers
  Path Keys:

    - masterid (number) – the id of the master

    - builderid (number) – the id of the builder

This path selects all workers for a given builder and a given master

`GET`
  `returns`

    `collection` of `worker`

path: /masters/{masterid}/builders/{builderid}/workers/{name}
  Path Keys:

    - masterid (number) – the id of the master

    - builderid (number) – the id of the builder

    - name (identifier) – the name of the worker

This path selects one worker by name for a given builder and a given master

`GET`
  `returns`

    `collection` of `worker`

path: /masters/{masterid}/builders/{builderid}/workers/{workerid}
  Path Keys:

    - masterid (number) – the id of the master

    - builderid (number) – the id of the builder

    - workerid (number) – the id of the worker

This path selects one worker by name for a given builder and a given master

`GET`
  `returns`

    `collection` of `worker`

path: /masters/{masterid}/workers
  Path Keys:

    masterid (number) – the id of the master

This path selects all workers for a given master

`GET`
  `returns`

    `collection` of `worker`

path: /masters/{masterid}/workers/{name}
  Path Keys:

    - masterid (number) – the id of the master

    - name (identifier) – the name of the worker

This path selects one worker by name for a given master

`GET`
  `returns`

    `collection` of `worker`

path: /masters/{masterid}/workers/{workerid}
  Path Keys:

    - masterid (number) – the id of the master

    - workerid (number) – the id of the worker

This path selects one worker by id for a given master

`GET`
  `returns`

    `collection` of `worker`

path: /workers

This path selects all workers

`GET`
  `returns`

    `collection` of `worker`

path: /workers/{name_or_id}
  Path Keys:

    name_or_id (number|identifier) – the name or id of a worker

This path selects a worker by name or id

`GET`
  `returns`

    `collection` of `worker`