Build

You can organize your test sessions on BrowserStack into builds. You can use this REST API to access the list of builds, get information about a specific build, update a specific build name, delete a build, and delete multiple builds at the same time.

Note: If you did not use the build capability in your tests, then your sessions would be put in an Untitled Build.
It is recommended that you organize your tests into builds and give them relevant names for you to be able to debug them properly using the Automate Dashboard

Get build list

GET /automate/builds.json

Fetch the 10 recent test builds that have run on BrowserStack using your username and access key. You can also limit the number of builds and paginate through your data.

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
https://api.browserstack.com/automate/builds.json

# Limit the number of builds to be displayed using "limit" parameter
curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
"https://api.browserstack.com/automate/builds.json?limit=5"

# Start the retrieval of records from a particular point using "offset" parameter
curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
"https://api.browserstack.com/automate/builds.json?limit=2\&offset=2"

# View a subset of results using "status" parameter
curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
"https://api.browserstack.com/automate/builds.json?status=running"

# View specific builds results using "projectId" parameter
curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
"https://api.browserstack.com/automate/builds.json?projectId=1234"

limit String

Specify the number of results to be displayed. The default value is 10, and the maximum value is 100.
offset String

Retrieve builds from a specific point using the offset parameter.
status String

The status parameter filters your results by the status of the build. The values accepted by this parameter are running, done, timeout, and failed.
projectId Integer

Retrieve all builds related to the specified project ID.

Response Attributes `200 OK` `Array`

Response

[
    {
        "automation_build":{
            "name":"pricing_build",
            "hashed_id":"ca9cccc228cf0e3ff3cb90dd62e2e2bfb4b20bc7",
            "duration":15611,
            "status":"running",
            "build_tag":null,
            "public_url":"https://automate.browserstack.com/dashboard/v2/public-build/MkdsKzRhanlWQmtpc"
        }
    },
    {
        "automation_build":{
            "name":"navigation_build",
            "hashed_id":"3b20f82b878c120e6edc7a2b373e65d20fb3ab7c",
            "duration":15601,
            "status":"running",
            "build_tag":null,
            "public_url":"https://automate.browserstack.com/dashboard/v2/public-build/LMNjdfsdfhbHBH"
        }
    },
    {...}
]

name String

Name of your build.
hashed_id String

ID of the build. (This hashed_id would be required for invoking the other endpoints in the Build API)
duration Integer

Duration of build execution.
status String

Status of the build (Either running, done, timeout, or failed).
public_url String

Public URL of your build.

Get build details

GET /automate/builds/{build_id}.json

Fetch detailed information about a specific build, including embedded sessions data. The response includes build metadata and up to 100 sessions created in the last 2 months.

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
  "https://api.browserstack.com/automate/builds/{build_id}.json"

# Filter sessions using optional query parameters
curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
  "https://api.browserstack.com/automate/builds/{build_id}.json?done=false&error=false"

build_id^* String

ID of the build (hashed_id from “Get build list”).
done String

Set to “false” to exclude sessions with status done, passed, or completed.
error String

Set to “false” to exclude sessions with status error or failed.
timeout String

Set to “false” to exclude sessions with status timeout.

Response Attributes `200 OK` `JSON`

Response

{
  "build": {
    "automation_build": {
      "name": "LCNC-19762 repro",
      "duration": 41,
      "status": "done",
      "hashed_id": "82404f20abe0b4beedc91dfb09293958c416984b",
      "build_tag": null
    },
    "sessions": [
      {
        "automation_session": {
          "name": "rehlko FF netlogs_ON",
          "duration": 41,
          "os": "Windows",
          "os_version": "10",
          "browser_version": "151.0",
          "browser": "firefox",
          "device": null,
          "status": "done",
          "hashed_id": "2976862176bf506476af9cdf782c026d5597008f",
          "reason": "CLIENT_STOPPED_SESSION",
          "build_name": "LCNC-19762 repro",
          "project_name": "lcnc",
          "build_hashed_id": "82404f20abe0b4beedc91dfb09293958c416984b",
          "test_priority": null
        }
      }
    ]
  }
}

name String

Name of your build.
hashed_id String

ID of the build, as passed in the request.
duration Integer

Duration of build execution, in seconds.
status String

Status of the build (running, done, failed, or timeout).
build_tag String

Tag associated with the build, set via the browserstack.build_tag or buildTag capability. null if not set.
Show 15 more
sessions Array

Array of session objects (capped at 100, limited to sessions from the last 2 months).
name String

Name of the session (nested under automation_session).
hashed_id String

ID of the session (nested under automation_session; use with the Session API endpoints).
duration Integer

Time taken to run the session in seconds (nested under automation_session).
os String

OS used for the session.
os_version String

Version of the OS used.
browser String

Browser used for the session.
browser_version String

Version of the browser used.
device String

Name of the device used. null for desktop sessions.
status String

Status of the session (nested under automation_session; values are running, done, error, timeout, or passed or failed when marked via the REST API or SDK).
reason String

Reason for the session status, for example CLIENT_STOPPED_SESSION or TIMEOUT. If the status was set by the user, this is the reason supplied with that update.
build_name String

Name of the build the session belongs to.
project_name String

Name of the project the build belongs to.
build_hashed_id String

ID of the build the session belongs to.
test_priority String

Priority set for the test, P0 to P3, via the session update API. null otherwise.

Note: The sessions array contains a maximum of 100 sessions (newest first), and only includes the sessions created in the last 2 months. For a complete list with pagination, use Get session list.

Note: This endpoint does not return public_url. That field exists only on Get build list.

Error Responses

404 - Not Found

The build ID is wrong, the build has no sessions, or the build belongs to a different group/sub-account than the credentials used.

{
  "message": "Build {build_id} does not exist. Please check the build id and try again."
}

404 - Not Found (App Automate build)

This endpoint is not applicable to App Automate framework builds (Espresso/XCUITest).

{
  "status": 404,
  "message": "Not Found"
}

401 - Unauthorized

Invalid username or access key.

{
  "message": "Unauthorized"
}

Update build details

PUT /automate/builds/{build_id}.json

You can update the name of your build after it completes using the PUT method.

Note: Renaming builds through REST API is not supported on the new dashboard experience.

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X PUT -H "Content-Type: application/json" \
-d "{\"name\":\"<build-name>\"}" 
https://api.browserstack.com/automate/builds/<build-id>.json

id^* String

ID of the build.
name^* String

The new build name that you want to set.
Accepted characters are A-Z, a-z, 0-9, ., :, -, [], /, @, &, ', _.
Character limit is 255.

Response Attributes `200 OK` `JSON`

Response

{
    "name":"pricing_updated_build",
    "duration":20,
    "status":"done",
    "hashed_id":"ede5ec7d6f24799707aa13860c0856dc4718d927",
    "build_tag":null
}

name String

Updated name of your build.
duration Integer

Duration of build execution.
status String

Status of the build.
hashed_id String

ID of the build as passed in the request.

Delete build

DELETE /automate/builds/{build_id}.json

You can delete a build on the server using the DELETE method. Please note that deleting a build will delete all the sessions contained within it. Builds once deleted cannot be recovered.

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X DELETE https://api.browserstack.com/automate/builds/<build-id>.json

id^* String

ID of the build.

Response Attributes `200 OK` `JSON`

Response

{
    "status":"ok",
    "message":"Build a4fb480a55efd6b3c558afb1ee051a7c337b8ef0 was deleted successfully."
}

status String

Status of deletion.
message String

Build deletion message.

Delete multiple builds

DELETE /automate/builds?buildId={build_id}

You can delete multiple builds on the server using the DELETE method. You can delete a maximum of 5 builds at a time. Builds once deleted cannot be recovered.

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X DELETE "https://api.browserstack.com/automate/builds?buildId=<build-id-1>\&buildId=<build-id-2>\&buildId=<build-id-3>"

id^* String

IDs of the builds to be deleted.

Response Attributes `200 OK` `JSON`

Response

{
    "message":"The following build(s) were deleted successfully: 83078c39baf5c12cbbfcbd26a788d05ddfad626c,55e9782d749f601d09571023f56a8f0101929428."
}

message String

Builds deletion message.

Post terminal logs

POST /automate/builds/{build_id}/terminallogs

Upload terminal logs for your build using the POST method.

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-L -X POST 'https://api-cloud.browserstack.com/automate/builds/<build_id>/terminallogs' \
-F 'file=@"/path/file.log"'

build_id^* String

ID of the test build available on the Automate dashboard.
file^* Path

Path to the terminal log file on your machine. The max allowed file size is 2MB.

Response Attributes `200 OK` `JSON`

Response

{
    "status":"success",
    "message":"File has been uploaded successfully!"
}

status String

Status of terminal log upload.
message String

Terminal log upload message.

Update build tags

PUT /automate/builds/{build_id}.json

You can update the build tags after the build completes using the PUT method.

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X PUT -H "Content-Type: application/json" \
-d "{\"build_tag\":\"<your-build-tag>\"}" https://api.browserstack.com/automate/builds/<build-id>.json

id^* String

ID of the build.
build_tag^* String

The new build tag that you want to set.

Response Attributes `200 OK` `JSON`

Response

{
    "name":"Selenium logs enabled",
    "duration":141,
    "status":"done",
    "hashed_id":"e8cde62c7e261edb013e82ac0096a650b4694b84",
    "build_tag":"reg"
}

name String

Name of your build.
duration Integer

Duration of build execution.
status String

Status of the build.
hashed_id String

ID of the build as passed in the request.
build_tag String

Updated tag of your build.

Note: You can add, edit, or delete the build tags using this API endpoint. To delete a build tag, simply pass an empty string. If you pass an empty string, the tagging will be removed.

Did this page help you?

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback

Build

Get build list

Request Parameters

limit String

offset String

status String

projectId Integer

Response Attributes 200 OK Array

name String

hashed_id String

duration Integer

status String

public_url String

Get build details

Request Parameters

build_id* String

done String

error String

timeout String

Response Attributes 200 OK JSON

name String

hashed_id String

duration Integer

status String

build_tag String

sessions Array

name String

hashed_id String

duration Integer

os String

os_version String

browser String

browser_version String

device String

status String

reason String

build_name String

project_name String

build_hashed_id String

test_priority String

Error Responses

Update build details

Request Parameters

id* String

name* String

Response Attributes 200 OK JSON

name String

duration Integer

status String

hashed_id String

Delete build

Request Parameters

id* String

Response Attributes 200 OK JSON

status String

message String

Delete multiple builds

Request Parameters

id* String

Response Attributes 200 OK JSON

message String

Post terminal logs

Request Parameters

build_id* String

file* Path

Response Attributes 200 OK JSON

status String

message String

Update build tags

Request Parameters

id* String

build_tag* String

Response Attributes 200 OK JSON

name String

duration Integer

status String

hashed_id String

build_tag String

We're sorry to hear that. Please share your feedback so we can do better

We're continuously improving our docs. We'd love to know what you liked

Response Attributes `200 OK` `Array`

build_id^* String

Response Attributes `200 OK` `JSON`

id^* String

name^* String

Response Attributes `200 OK` `JSON`

id^* String

Response Attributes `200 OK` `JSON`

id^* String

Response Attributes `200 OK` `JSON`

build_id^* String

file^* Path

Response Attributes `200 OK` `JSON`

id^* String

build_tag^* String

Response Attributes `200 OK` `JSON`