Run XCUITest builds on Apple TV via App Automate API

Start a build on a dedicated Apple TV device in your group and get the build status and test case results.

Each build represents an execution of your XCUITest test suite on one or more Apple TV devices on BrowserStack. Use these REST API endpoints to start a build and fetch its status.

Execute a build

POST /app-automate/xcuitest/v2/build

Start the execution of a new build on Apple TV devices. In the request, specify the app under test, the XCUITest test suite, and the list of Apple TV devices, and set dedicatedDevice to true. Apple TV devices aren’t part of the public device catalog, so a request without dedicatedDevice returns an invalid device error. To pin the build to one specific device, also pass deviceId. Every build has a unique build_id, which is returned in the response.

Some build parameters available for iOS aren’t supported on Apple TV. For the supported and unsupported parameters, see Execute your XCUITest tests on Apple TV.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST "https://api-cloud.browserstack.com/app-automate/xcuitest/v2/build" \
-d '{"app": "<app_url>", "testSuite": "<test_suite_url>", "devices": ["Apple TV 4K-26.2"], "dedicatedDevice": true}' \
-H "Content-Type: application/json"

app^* String

Specify the application under test. Use app_url or custom_id of a previously uploaded app. Learn more about app API
testSuite^* String

Specify an XCUI test suite. Use test_suite_url or custom_id of a previously uploaded test suite. Learn more about testSuite API
devices^* Array[String]

List of Apple TV devices to execute your tests on. Only Apple TV 4K devices running tvOS 26.x are supported.
Example: ["Apple TV 4K-26.2"]
dedicatedDevice^* Boolean

Set to true to run the build on a device dedicated to your group. Apple TV devices aren’t part of the public device catalog, so this parameter is required. Learn more about running tests on dedicated Apple TV devices
deviceId String

ID of one specific Apple TV device in your group to pin the build to. If you omit it, the build runs on any dedicated Apple TV in your group. Use with dedicatedDevice set to true.
Show 14 more
project String

Unique identifier to logically group multiple builds together. Only letters (A-Z, a-z), digits (0-9), periods (.), colons (:) and underscores (_) are allowed. Any other characters are ignored.
customBuildName String

A custom name for your build. Accepted characters are A-Z, a-z, 0-9, ., :, -, [, ], /, @, &, ', _. All other characters are ignored. Invalid names fall back to the default naming workflow. Learn more about custom build names
buildTag String

Unique identifier to tag builds. Only letters (A-Z, a-z), digits (0-9), periods (.), colons (:) and underscores (_) are allowed. Any other characters are ignored.
Example: Reg
only-testing String

Filter test cases by selected classes or tests in the test suite. Specify a list of fully qualified class/test name(s).
Example: ["SampleXCUITests/testAlert", "SampleXCUITests/testText"]
skip-testing String

Filter test cases by skipping selected classes or tests in the test suite. Specify a list of fully qualified class/test name(s).
Example: ["SampleXCUITests/testAlert"]
callbackURL String

Specify a callback URL to enable BrowserStack to notify you upon the completion of your build.
projectNotifyURL String

Specify a callback URL to enable BrowserStack to notify you upon the completion of all builds under the given project. You receive a callback if no new builds are triggered for 5 minutes and all existing builds have finished execution.

Note: Set this parameter along with the project parameter.
setEnvVariables Object

Use this parameter to pass custom key and value pairs that can be accessed as environment variables by your XCUI test suite. Acceptable character limit for the key is 30 and for the value is 100 characters.
Example: {"key1":"value1", "key2":"value2"}
idleTimeout Integer

Use this parameter to specify the maximum time limit for which your test execution can remain idle. If it exceeds this threshold, your build status changes to timed out. The accepted range is 60 to 900 seconds. By default, it’s set to 900 seconds.
singleRunnerInvocation Boolean

Execute test cases together in a single process. By default, it’s set to false.
enableResultBundle Boolean

Enable generating an xcresult bundle for your XCUI test build execution. By default, it’s set to false.
networkLogs Boolean

Capture network logs (data such as network traffic, latency, HTTP requests and responses in the HAR format) for your test execution. By default, it’s set to false.
deviceLogs Boolean

Capture device logs (system logs specific to your application) for your test execution. By default, it’s set to false.
video Boolean

Enable or disable video recording for your test execution. By default, it’s set to true.

Response attributes `200` `application/json`

Response

{
    "message": "Success",
    "build_id": "<build_id>"
}

message String

Status of the request.
build_id String

A unique identifier for your test execution.
Example: 5c5ab4338cec13aeb78f7a6977344556ac00bccd6

Get build status

GET /app-automate/xcuitest/v2/builds/{buildID}

After a build starts, fetch its status using this endpoint. The response includes the overall summary of your build and the results for each test case.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X GET "https://api-cloud.browserstack.com/app-automate/xcuitest/v2/builds/<build_id>"

buildID^* String

Unique build ID for your XCUITest build execution.
Example: 57dd68e05f76ca3c9c0d4600fd78ae064fa537bb

Response attributes `200` `application/json`

Response

{
    "id": "<build_id>",
    "framework": "xcuitest",
    "duration": 83,
    "status": "failed",
    "input_capabilities": {
        "devices": [
            "Apple TV 4K-26.2"
        ],
        "app": "bs://<hashed_app_id>",
        "testSuite": "bs://<hashed_test_suite_id>"
    },
    "start_time": "2026-11-03 07:43:49 UTC",
    "app_details": {
        "url": "bs://<hashed_app_id>",
        "bundle_id": "com.example.tvapp",
        "version": "1.0",
        "name": "YourTVApp.ipa"
    },
    "test_suite_details": {
        "url": "bs://<hashed_test_suite_id>",
        "bundle_id": "com.example.tvapp.uitests",
        "version": "",
        "name": "YourTVAppUITests.zip"
    },
    "devices": [
        {
            "device": "Apple TV 4K",
            "os": "<os_name>",
            "os_version": "26.2",
            "sessions": [
            {
                "id": "<session_id>",
                "status": "failed",
                "start_time": "2026-11-03 07:44:07 +0000",
                "duration": 62,
                "testcases": {
                    "count": 9,
                    "status": {
                        "passed": 3,
                        "failed": 6,
                        "skipped": 0,
                        "timedout": 0,
                        "error": 0,
                        "running": 0,
                        "queued": 0
                    }
                }
            }]
        }
    ]
}

id String

Unique build ID for your test execution.
Example: 4fc55a08d7e33651d962ad676c7d6a0a08902702
framework String

Name of the automation framework. This is set to XCUITest.
duration Integer

Total duration for build completion (in seconds). This includes the time taken to install the app, test suite, setting up the device along with the test execution time of all the test cases.
status String

Status of your build execution. This is computed based on the status of every test case executed in your entire test suite. Learn more about viewing test results
input_capabilities Object

Details about the input parameters passed while starting the build execution.

▶ SHOW VALUES
- devices Array
  
  List of devices on which the build is executed.
  Example: ["iPhone X-11.0", "iPhone 8-11.0"]
- project String
  
  Name of your project which is set inside the project parameter inside the build execution API.
- app String
  
  The app_url of the app uploaded on BrowserStack.
  Example: bs://9c6dcb5649a8280ca800075bfd8f151115bba6b3
- testSuite String
  
  The test-url of the test-suite uploaded on BrowserStack.
  Example: bs://89c874f21852ba57957a3fdc33f47514288c4ba1
Show 4 more
start_time String

Timestamp at which the build execution was started.
app_details Object

Details about the application under test uploaded on BrowserStack.

▶ SHOW VALUES
- url String
  
  The app_url of the app(.ipa) file uploaded on BrowserStack.
- bundle_id String
  
  Bundle ID of the app.
- version String
  
  Version code of the app.
- name String
  
  Name of your app(.ipa) file.
test_suite_details Object

Details about the test suite uploaded on BrowserStack.

▶ SHOW VALUES
- url String
  
  The test_url of the XCUI test-suite(.zip) file uploaded on BrowserStack.
- bundle_id String
  
  Bundle ID or the package name of the test-suite.
- version String
  
  Version code of the test-suite. The value is null.
- name String
  
  Name of your XCUI test-suite(.zip) file.
devices Array

Test execution details for each device in the build.

▶ SHOW VALUES
- device String
  
  The name of the device.
- os String
  
  By default, this is set to iOS.
- os_version String
  
  iOS OS version.
- sharding Boolean
  
  Indicates if the sharding is enabled for this build.
- sessions Array
  
  If sharding is disabled, each session is the execution of your test-suite on a single device. Thus, each device will have a single session. If sharding is enabled, each session is the execution of a single shard on a single device. Thus, each device will have multiple sessions (one for each shard).
  
  ▶ SHOW VALUES
  - id String
    
    A unique session ID.
    Example: 09a018967ec8b2dc5dd391de1130f69463840039
  - status String
    
    Status of this session.
  - start_time String
    
    Timestamp at which the session execution started.
  - duration String
    
    Duration of the session execution.
  - testcases Object
    
    Test case execution summary for this session.
    
    ▶ SHOW VALUES
    - count Integer
      
      The total number of test-cases in this session.
    - status Object
      
      Count of test-cases by each status type.
      
      ▶ SHOW VALUES
      - passed Integer
        
        Total count of test cases with explicit test assertions that marks the test as passed.
      - failed Integer
        
        Total count of test cases with uncaught exceptions or explicit test assertions that marks test as failed.
      - skipped Integer
        
        Total count of test cases that never got executed by the test runner.
      - timedout Integer
        
        Total count of test cases that got timed-out.
      - error Integer
        
        Total count of test cases that errored due to an unanticipated issue on BrowserStack.
      - running Integer
        
        Total count of test cases that are currently under execution.
      - queued Integer
        
        Total count of test cases that are queued for execution.

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

Run XCUITest builds on Apple TV via App Automate API

Execute a build

Request parameters

app* String

testSuite* String

devices* Array[String]

dedicatedDevice* Boolean

deviceId String

project String

customBuildName String

buildTag String

only-testing String

skip-testing String

callbackURL String

projectNotifyURL String

setEnvVariables Object

idleTimeout Integer

singleRunnerInvocation Boolean

enableResultBundle Boolean

networkLogs Boolean

deviceLogs Boolean

video Boolean

Response attributes 200 application/json

message String

build_id String

Get build status

Request parameters

buildID* String

Response attributes 200 application/json

id String

framework String

duration Integer

status String

input_capabilities Object

devices Array

project String

app String

testSuite String

start_time String

app_details Object

url String

bundle_id String

version String

name String

test_suite_details Object

url String

bundle_id String

version String

name String

devices Array

device String

os String

os_version String

sharding Boolean

sessions Array

id String

status String

start_time String

duration String

testcases Object

count Integer

status Object

passed Integer

failed Integer

skipped Integer

timedout Integer

error Integer

running Integer

queued Integer

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

app^* String

testSuite^* String

devices^* Array[String]

dedicatedDevice^* Boolean

Response attributes `200` `application/json`

buildID^* String

Response attributes `200` `application/json`