Skip to main content

Builds API Endpoints

Builds are a means of categorizing your jobs on Sauce Labs, allowing you to view related jobs together for greater insight. The Builds API methods retrieve information about the builds and the jobs assigned to them.

note

Builds are exclusive to the device source on which the jobs were run, meaning you cannot group real device tests and emulator/simulator tests in the same build. Therefore, all Build API methods require a {build_source} parameter.

Refer to Getting Started for Authentication and Server information.

Lookup Builds​

GET /v2/builds/{build_source}/

Queries the requesting account and returns a summary of each build matching the query, including the ID value, which may be a required parameter of other API calls related to a specific build.You can narrow the results of your query using any of the optional filtering parameters.

Parameters​

build_source

| PATH | REQUIRED | ENUM |

The type of device for which you are getting builds. Valid values are:

  • rdc - Real Device Builds
  • vdc - Emulator or Simulator Builds

user_id

| QUERY | OPTIONAL | STRING |

Returns any builds owned by the specified user that the authenticated user is authorized to view. You can look up the IDs of users in your organization using the Lookup Users endpoint.

org_id

| QUERY | OPTIONAL | STRING |

Returns all builds in the specified organization that the authenticated user is authorized to view.

group_id

| QUERY | OPTIONAL | STRING |

Returns all builds associated with the specified group that the authenticated user is authorized to view.

team_id

| QUERY | OPTIONAL | STRING |

Returns all builds for the specified team that the authenticated user is authorized to view.

status

| QUERY | OPTIONAL | ARRAY |

Returns only builds where the status matches the list of values specified. Valid values are:

  • running - Any job in the build has a state of running, new, or queued.
  • error - The build is not running and at least one job in the build has a state of errored.
  • failed - The build is not running or error and at least one job in the build has a state of failed.
  • complete - The build is not running, error, or failed, but the number of jobs with a state of finished does not equal the number of jobs marked passed, so at least one job has a state other than passed.
  • success -- All jobs in the build have a state of passed.

start

| QUERY | OPTIONAL | DATE-TIME |

Returns only builds where the earliest job ran on or after this Unix timestamp.

end

| QUERY | OPTIONAL | DATE-TIME |

Returns only builds where the latest job ran on or before this Unix timestamp.

limit

| QUERY | OPTIONAL | INTEGER |

The maximum number of builds to return in the response.

name

| QUERY | OPTIONAL | STRING |

Returns builds with a matching build name.

offset

| QUERY | OPTIONAL | INTEGER |

Begins the set of results at this index number.

sort

| QUERY | OPTIONAL | ENUM |

Sorts the results in alphabetically ascending or descending order. Valid values are:

  • asc - Ascending
  • desc - Descending

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-west-1.saucelabs.com/v2/builds/vdc/' | json_pp

Responses​

200Success. Build info returned.
404Not found.
422Validation Error. One or more of the parameters in the request is not formatted properly. The error response msg property may contain additional details about the specific failure.
Sample Response
{
    "builds": [
        {
            "creation_time": 1631824314,
            "deletion_time": null,
            "end_time": 1631824422,
            "group_id": "8cdb4afe7cba4846b5cae339a87e3b70",
            "id": "780fbea7d2313b258a935e1b7f7e48e2",
            "jobs": {
                "completed": 0,
                "errored": 0,
                "failed": 0,
                "finished": 3,
                "passed": 3,
                "public": 0,
                "queued": 0,
                "running": 0
            },
            "modification_time": 1631824426,
            "name": "DevX SS",
            "org_id": "7fb25570b4064716b9b6daae1a846790",
            "owner_id": "5c207d581a48462e9c0eb21d30b931e2",
            "passed": null,
            "public": false,
            "run": 0,
            "start_time": 1631824314,
            "status": "success",
            "team_id": "98b9f34e596047d99abba56f517846a9"
        },
        {more build results...}
    ]
}

Get a Specific Build​

GET /v2/builds/{build_source}/{build_id}/

Retrieve the details related to a specific build by passing its unique ID in the request.

Parameters​

build_source

| PATH | REQUIRED | ENUM |

The type of test device associated with the build. Valid values are:

  • rdc - Real Device Builds
  • vdc - Emulator or Simulator Builds

build_id

| PATH | REQUIRED | STRING |

The unique identifier of the build to retrieve. You can look up build IDs in your organization using the Lookup Builds endpoint.

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-west-1.saucelabs.com/v2/builds/vdc/6027d9672cc430c89582fa69e96ae7b8/' | json_pp

Responses​

200Success. Build info returned.
404Not found.
422Validation Error. One or more of the parameters in the request is not formatted properly. The error response msg property may contain additional details about the specific failure.
Sample Response
{
    "creation_time": 1632226660,
    "deletion_time": null,
    "end_time": 1632226689,
    "group_id": "8cdb4afe7cba4846b5cae339a87e3b70",
    "id": "6027d9672cc430c89582fa69e96ae7b8",
    "jobs": {
        "completed": 0,
        "errored": 0,
        "failed": 1,
        "finished": 3,
        "passed": 2,
        "public": 0,
        "queued": 0,
        "running": 0
    },
    "modification_time": 1632226691,
    "name": "insights-vdc-test-20210921-121737",
    "org_id": "7fb25570b4064716b9b6daae1a846790",
    "owner_id": "c315e56ecd954018b9a0bc6e85732826",
    "passed": null,
    "public": false,
    "run": 0,
    "start_time": 1632226659,
    "status": "failed",
    "team_id": "64e0d884a79b4f81ba6bc1025c10eb63"
}

Lookup the Build for a Specific Job​

GET /v2/builds/{build_source}/jobs/{job_id}/build/

Retrieves the build details for a known job.

Parameters​

build_source

| PATH | REQUIRED | ENUM |

The type of test device associated with the job and build. Valid values are:

  • rdc - Real Device Builds
  • vdc - Emulator or Simulator Builds

job_id

| PATH | REQUIRED | STRING |

The unique identifier of the job whose build you are looking up. You can look up job IDs in your organization using the Get Jobs endpoint.

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-west-1.saucelabs.com/v2/builds/vdc/jobs/eacde1439dd0437e807b61845d8e92b8/build/' | json_pp

Responses​

200Success. Build info returned.
404Not found.
422Validation Error. One or more of the parameters in the request is not formatted properly. The error response msg property may contain additional details about the specific failure.
Sample Response
{
    "creation_time": 1631824314,
    "deletion_time": null,
    "end_time": 1631824422,
    "group_id": "8cdb4afe7cba4846b5cae339a87e3b70",
    "id": "780fbea7d2313b258a935e1b7f7e48e2",
    "jobs": {
        "completed": 0,
        "errored": 0,
        "failed": 0,
        "finished": 3,
        "passed": 3,
        "public": 0,
        "queued": 0,
        "running": 0
    },
    "modification_time": 1631824426,
    "name": "DevX SS",
    "org_id": "7fb25570b4064716b9b6daae1a846790",
    "owner_id": "5c207d581a48462e9c0eb21d30b931e2",
    "passed": null,
    "public": false,
    "run": 0,
    "start_time": 1631824314,
    "status": "success",
    "team_id": "98b9f34e596047d99abba56f517846a9"
}

Lookup Jobs in a Build​

GET /v2/builds/{build_source}/{build_id}/jobs/

Returns information about all jobs associated with the specified build. You can limit which jobs are returned using any of the optional filtering parameters.

Parameters​

build_source

| PATH | REQUIRED | ENUM |

The type of test device associated with the build and its jobs. Valid values are:

  • rdc - Real Device Builds
  • vdc - Emulator or Simulator Builds

build_id

| PATH | REQUIRED | STRING |

The unique identifier of the build whose jobs you are looking up. You can look up build IDs in your organization using the Lookup Builds endpoint.

modified_since

| QUERY | OPTIONAL | DATE-TIME |

Returns only jobs that have been modified after this unicode timestamp.

completed

| QUERY | OPTIONAL | BOOLEAN |

Returns jobs based on whether they completed, meaning the tests ran uninterrupted to completion:

  • true - Return jobs that have a completed state of true.
  • false - Return jobs that have a completed state of false.

errored

| QUERY | OPTIONAL | BOOLEAN |

Returns jobs based on their errored state:

  • true - Return jobs that have an errored state of true.
  • false - Return jobs that have an errored state of false.

failed

| QUERY | OPTIONAL | BOOLEAN |

Returns jobs based on their failed state:

  • true - Return jobs that have a failed state of true.
  • false - Return jobs that have a failed state of false.

finished

| QUERY | OPTIONAL | BOOLEAN |

Returns jobs based on whether they have finished, meaning they are no longer running, but may not have run to completion:

  • true - Return jobs that have a finished state of true.
  • false - Return jobs that have a finished state of false.

new

| QUERY | OPTIONAL | BOOLEAN |

Returns jobs based on their new state:

  • true - Return jobs that have a new state of true.
  • false - Return jobs that have a new state of false.

passed

| QUERY | OPTIONAL | BOOLEAN |

Returns jobs based on their passed state:

  • true - Return jobs that have a passed state of true.
  • false - Return jobs that have a passed state of false.

public

| QUERY | OPTIONAL | BOOLEAN |

Returns jobs based on whether they were run on public devices:

  • true - Return jobs that have a public state of true.
  • false - Return jobs that have a public state of false.

queued

| QUERY | OPTIONAL | BOOLEAN |

Returns jobs based on whether their current state is queued:

  • true - Return jobs that have a queued state of true.
  • false - Return jobs that have a queued state of false.

running

| QUERY | OPTIONAL | BOOLEAN |

Returns jobs based on whether they are currently in a running state:

  • true - Return jobs that are currently running.
  • false - Return jobs that are not currently running.

faulty

| QUERY | OPTIONAL | BOOLEAN |

Returns jobs based on whether they are identified as faulty, meaning either errored or failed state is true.

  • true - Return jobs that have a faulty state of true.
  • false - Return jobs that have a faulty state of false.

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-west-1.saucelabs.com/v2/builds/vdc/a633354c3bc232ee8871f24332046cb9/jobs/?finished=true' | json_pp

Responses​

200Success. Build info returned.
403Forbidden. The authenticating account does not have permission to make the request.
404Not found.
422Validation Error. One or more of the parameters in the request is not formatted properly. The error response msg property may contain additional details about the specific failure.
Sample Response
{
    "jobs": [
        {
            "creation_time": 1632236598,
            "deletion_time": null,
            "id": "ac50bd0253834f78abdee6d5afea89ba",
            "modification_time": 1632236607,
            "state": {
                "completed": false,
                "errored": false,
                "failed": false,
                "finished": true,
                "new": false,
                "passed": true,
                "public": false,
                "queued": false,
                "running": false
            }
        },
        {more job results...}
    ]
}