# 3.5.23. step

resource type: step
  Attributes:

    - stepid (integer) – the unique ID of this step

    - buildid (integer) – ID of the build containing this step

    - complete (boolean) – true if this step is complete

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

    - hidden (boolean) – true if the step should not be displayed

    - name (identifier) – the step name, unique within the build

    - number (integer) – the number of this step (sequential within the build)

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

    - started_at? (date) – time at which this step started, or None if it hasn’t started yet

    - locks_acquired_at? (date) – time at which this step acquired locks (if any), or None if the locks haven’t been acquired

    - state_string (string) – a string giving detail on the state of the build. The first is usually one word or phrase; the remainder are sized for one-line display

    - urls[] –

      a list of URLs associated with this step

      - `name` (string)

      - `url` (string)

This resource type describes a step in a build. Steps have unique IDs, but are most commonly accessed by name in the context of their containing builds.

## 3.5.23.1. Update Methods

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

class buildbot.data.steps.Step
  newStep(buildid, name)
    Parameters:

      - buildid (integer) – buildid containing this step

      - name (50-character identifier) – name for the step

    Returns:

      (stepid, number, name) via Deferred

    Create a new step and return its ID, number, and name. Note that the name may be different from the requested name if that name was already in use. The state strings for the new step will be set to ‘pending’.

  startStep(stepid, started_at=None, locks_acquired=False)
    Parameters:

      - stepid (integer) – the step to modify

      - started_at (integer) – optionally specify the startup time value. If not specified, then int(self.master.reactor.seconds()) will be used.

      - locks_acquired (boolean) – True if all locks are already acquired at the step startup. This effectively calls set_step_locks_acquired_at(stepid, locks_acquired_at=started_at)

    Start the step.

  set_step_locks_acquired_at(stepid, locks_acquired_at=None)
    Parameters:

      - stepid (integer) – the step to modify

      - locks_acquired_at (integer) – optionally specify the timestamp value. If not specified, then int(self.master.reactor.seconds()) will be used.

    Update step locks_acquired_at timestamp.

  setStepStateString(stepid, state_string)
    Parameters:

      - stepid (integer) – the step to modify

      - state_string (unicode) – new state strings for this step

    Replace the existing state string for a step with a new list.

  addStepURL(stepid, name, url):
    Parameters:

      - stepid (integer) – the step to modify

      - name (string) – the url name

      - url (string) – the actual url

    Returns:

      None via deferred

    Add a new url to a step. The new url is added to the list of urls.

  finishStep(stepid, results, hidden)
    Parameters:

      - stepid (integer) – the step to modify

      - results (integer) – the step’s results

      - hidden (boolean) – true if the step should not be displayed

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

## 3.5.23.2. Endpoints

path: /builders/{builderid_or_buildername}/builds/{build_number}/steps
  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 all steps for the given build

`GET`
  `returns`

    `collection` of `step`

path: /builders/{builderid_or_buildername}/builds/{build_number}/steps/{step_name}
  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

    - step_name (identifier) – the slug name of the step

This path selects a specific step for the given build

`GET`
  `returns`

    `collection` of `step`

path: /builders/{builderid_or_buildername}/builds/{build_number}/steps/{step_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

    - step_number (number) – the number of the step

This path selects a specific step given its step number

`GET`
  `returns`

    `collection` of `step`

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

    buildid (number) – the id of the build

This path selects all steps of a build

`GET`
  `returns`

    `collection` of `step`

path: /builds/{buildid}/steps/{step_number_or_name}
  Path Keys:

    - buildid (number) – the id of the build

    - step_number_or_name (identifier|number) – the name or number of the step

This path selects one step of a build

`GET`
  `returns`

    `collection` of `step`