# 3.5.3. build

resource type: build
  Attributes:

    - buildid (integer) – the unique ID of this build

    - number (integer) – the number of this build (sequential for a given builder)

    - builderid (integer) – id of the builder for this build

    - buildrequestid (integer) – build request for which this build was performed, or None if no such request exists

    - workerid (integer) – the worker this build ran on

    - masterid (integer) – the master this build ran on

    - started_at (date) – time at which this build started

    - complete (boolean) – true if this build is complete. Note that this is a calculated field (from complete_at != None). Ordering by this field is not optimized by the database layer.

    - complete_at? (date) – time at which this build was complete, or None if it’s still running

    - locks_duration_s (integer) – time spent acquiring locks so far, not including any running steps

    - properties? (sourcedproperties) – a dictionary of properties attached to build.

    - results? (integer) – the results of the build (see Build Result Codes), or None if not complete

    - state_string (string) – a string giving detail on the state of the build.

`example`

>     {
>         "builderid": 10,
>         "buildid": 100,
>         "buildrequestid": 13,
>         "workerid": 20,
>         "complete": false,
>         "complete_at": null,
>         "masterid": 824,
>         "number": 1,
>         "results": null,
>         "started_at": 1451001600,
>         "state_string": "created",
>         "properties": {}
>     }

This resource type describes completed and in-progress builds. Much of the contextual data for a build is associated with the build request, and through it the buildset.

Note

The properties field of a build is only filled out if the properties filterspec is set. That means the `property` filter allows one to request properties through the Builds DATA API like so:

> - api/v2/builds?property=* (returns all properties)

> - api/v2/builds?property=propKey1&property=propKey2 (returns the properties that match the given keys)

> - api/v2/builds?property=propKey1&property=propKey2&limit=30 (filters combination)

Important

When combined with the `field` filter, for someone to get the build properties, they should ensure the properties field is set:

- api/v2/builds?field=buildid&field=properties&property=workername&property=user

## 3.5.3.1. Update Methods

All update methods are available as attributes of `master.data.updates`.

class buildbot.data.builds.Build
  newBuild(builderid, buildrequestid, workerid)
    Parameters:

      - builderid (integer) – id of the builder performing this build

      - buildrequestid (integer) – id of the build request being built

      - workerid (integer) – id of the worker on which this build is performed

    Returns:

      (buildid, number) via Deferred

    Create a new build resource and return its ID. The state strings for the new build will be set to ‘starting’.

  setBuildStateString(buildid, state_string)
    Parameters:

      - buildid (integer) – the build to modify

      - state_string (unicode) – new state string for this build

    Replace the existing state strings for a build with a new list.

  finishBuild(buildid, results)
    Parameters:

      - buildid (integer) – the build to modify

      - results (integer) – the build’s results

    Mark the build as finished at the current time, with the given results.

## 3.5.3.2. Endpoints

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

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

This path selects all builds for a builder (can return lots of data!)

`GET`
  `returns`

    `collection` of `build`

path: /builders/{builderid_or_buildername}/builds/{build_number}
  Path Keys:

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

    - build_number (number) – the number of the build within the builder

This path selects a specific build by builderid and buildnumber

`GET`
  `returns`

    `collection` of `build`

POST with method: /builders/{builderid_or_buildername}/builds/{build_number} (method=stop)
  Body keys:

    - method (string) – must be `stop`

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

    - results (integer) – optionally results value override (default CANCELLED)

POST with method: /builders/{builderid_or_buildername}/builds/{build_number} (method=rebuild)
  Body keys:

    method (string) – must be `rebuild`

path: /buildrequests/{buildrequestid}/builds
  Path Keys:

    buildrequestid (number) – the id of the buildrequest

`GET`
  `returns`

    `collection` of `build`

path: /builds

`GET`
  `returns`

    `collection` of `build`

path: /builds/{buildid}
  Path Keys:

    buildid (number) – the id of the build

This path selects a build by id

`GET`
  `returns`

    `collection` of `build`

POST with method: /builds/{buildid} (method=stop)
  Body keys:

    - method (string) – must be `stop`

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

POST with method: /builds/{buildid} (method=rebuild)
  Body keys:

    method (string) – must be `rebuild`

path: /builds/{buildid}/triggered_builds
  Path Keys:

    buildid (number) – the id of the build

This selects all builds that have been triggered by this particular build

`GET`
  `returns`

    `collection` of `build`