Table of Contents
APP AUTOMATE API

Sessions

Each build consists of one or more test sessions. Each session is a remote Appium webdriver session executed on a single BrowserStack device. Each session has a unique identifier (session ID) associated with it. Use our REST API to access any given test session’s execution details and debugging information.

Get session details

GET /app-automate/sessions/{sessionID}.json

Get details of a test session including its status and debugging information such as Appium logs and test video recording.

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X GET "https://api-cloud.browserstack.com/app-automate/sessions/22dbfb187486090d974a11ac91t65722988e0705.json"
  • sessionID* String

    The unique identifier of the test session.

Response Attributes 200 OK application/json

Response

{
  "automation_session": {
    "name": "login_test",
    "duration": 39,
    "os": "android",
    "os_version": "9.0",
    "browser_version": "app",
    "browser": null,
    "device": "OnePlus 6T",
    "status": "passed",
    "hashed_id": "22dbfb187486090d974a11ac91t65722988e0705",
    "reason": "CLIENT_STOPPED_SESSION",
    "build_name": "SampleBuild",
    "project_name": "SampleProject",
    "logs": "https://app-automate.browserstack.com/builds/g0726012b6rb0a4c79122d6048c7b8767677ad61/sessions/22dbfb187486090d974a11ac91t65722988e0705/logs",
    "browser_url": "https://app-automate.browserstack.com/builds/g0726012b6rb0a4c79122d6048c7b8767677ad61/sessions/22dbfb187486090d974a11ac91t65722988e0705",
    "public_url": "https://app-automate.browserstack.com/builds/g0726012b6rb0a4c79122d6048c7b8767677ad61/sessions/22dbfb187486090d974a11ac91t65722988e0705?auth_token=9876563e667cd765467e6fea5a834121e568be899505699b",
    "appium_logs_url": "https://api.browserstack.com/app-automate/builds/g0726012b6rb0a4c79122d6048c7b8767677ad61/sessions/22dbfb187486090d974a11ac91t65722988e0705/appiumlogs",
    "video_url": "https://app-automate.browserstack.com/sessions/22dbfb187486090d974a11ac91t65722988e0705/video?token=ZnN6cGt1WTY4UlJrdTVzcE5xcGhWTldvZGVlRydys4aWc9PSaHVkTS84UnNhdU54aWtmVU9lWHFPVWt3TM5UjJXdkNmSjdHUGxuLzBmQWFXamcyS3htM3l0tc0xZempkdnVlQ3BrN1A5OWFILzNZdz09--37203d41d45d3d42e1fb75266e527721af3ab65d&source=rest_api&diff=60060.827966758",
    "device_logs_url": "https://api.browserstack.com/app-automate/builds/g0726012b6rb0a4c79122d6048c7b8767677ad61/sessions/22dbfb187486090d974a11ac91t65722988e0705/devicelogs",
    "app_details": {
      "app_url": "bs://c8ddcb5649a8280ca800075bfd8f151115bba6b3",
      "app_name": "com.sample.loginapplication",
      "app_version": "1.0",
      "app_custom_id": "LoginApp",
      "uploaded_at": "2020-09-09T18:14:20.000Z"
    }
  }
}
  • automation_session Object

    Details of test session.

    SHOW VALUES
    • name String

      Name of your test session.

    • duration String

      Total duration of test session.

    • os String

      OS on which your session was executed. Possible values are android and ios

    • os_version String

      OS version on which your session was executed.

    • browser_version String

      The value will always be equal to app for App Automate test sessions.

    • device String

      Name of the device on which session was executed.
      Example Google Pixel 3

    • status String

      Status of the session. The possible values for session status are :

      Key Value
      running Test session is currently running.
      done The test session completed. This happens when your test script issues a driver.quit Appium command to BrowserStack to terminate a running session.
      timeout The test session was idle for 90 seconds. If no additional Appium commands are recevied for 90 seconds, the test session is terminated, and the session status is updated to Timed out.
      failed The test session encountered an error.
    • reason String

      Reason for session termination. For e.g., its set to CLIENT_STOPPED_SESSION when a session is terminated upon execution of driver.quit command.

    • build_name String

      Name of the build. If a build name was not set, the default value is Untitled Project

    • project_name String

      Name of the project. If a project name was not set, the default value is Untitled Build

    • logs String

      URL to fetch text logs for your test session.

    • public_url String

      Publicly accessible URL to share the report of this test session with anyone outside your team.

    • appium_logs_url String

      URL to fetch Appium logs for your test session.

    • video_url String

      URL to fetch video recording for your test session.

    • device_logs_url String

      URL to fetch device logs for your test session.

    • app_details Object

      Details about application under test for your test session.

      SHOW VALUES
      • app_url String

        The app_url of your uploaded app on BrowserStack.

      • app_name String

        Package name of the app.

      • app_version String

        Version of the app.

      • app_custom_id String

        Custom ID defined for the uploaded app.
        Example: SampleApp.

      • uploaded_at String

        Timestamp at which app was uploaded on BrowserStack.

Update session status

PUT /app-automate/sessions/{sessionID}.json

Once the test session’s execution is completed, mark its status as passed or failed for your internal reference. Optionally, you can also record a reason for its status. Learn more about marking tests as passed or failed.

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X PUT "https://api-cloud.browserstack.com/app-automate/sessions/22dbfb187486090d974a11ac91t65722988e0705.json" \
-d '{"status": "failed", "reason": "The element was not visible on the screen"}' \
-H "Content-Type: application/json"
  • sessionID* String

    Unique identifier of the test session.

  • status* String

    Set the test status as passed or failed.

  • reason String

    You can also include a reason for your test’s passed or failed status.

Response Attributes 200 OK application/json

Response

{
  "automation_session": {
    "name": "login_test",
    "duration": 39,
    "os": "android",
    "os_version": "9.0",
    "browser_version": "app",
    "browser": null,
    "device": "OnePlus 6T",
    "status": "failed",
    "hashed_id": "22dbfb187486090d974a11ac91t65722988e0705",
    "reason": "The element was not visible on the screen",
    "build_name": "SampleBuild",
    "project_name": "SampleProject"
  }
}
  • name String

    Name of your session.

  • duration Integer

    Total time taken to execute the test session.

  • os String

    OS on which the session executed

  • os_version String

    OS version on which your session was executed.

  • browser_version String

    Version of the browser

  • browser String

    Browser on which the session executed

  • device String

    Name of the device on which session executed

  • status String

    Status of the session

  • hashed_id String

  • reason String

    Reason for test failure

  • build_name String

    Name of the build

  • project_name String

    Name of the project

  • test_priority String

Delete a session

DELETE /app-automate/sessions/{sessionID}.json

Delete a test session that previously ran on BrowserStack.

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X DELETE "https://api-cloud.browserstack.com/app-automate/sessions/22dbfb187486090d974a11ac91t65722988e0705.json"
  • sessionID* String

    The session ID of the session.

Response Attributes 200 OK application/json

Response

{
    "status": "ok",
    "message": "Session 22dbfb187486090d974a11ac91t65722988e0705 was deleted successfully."
}
  • status String

    Status of your delete request.

  • message String

    Confirmation message for successful deletion of the session.

Get text logs

GET /app-automate/builds/{buildID}/sessions/{sessionID}/logs

Access the logs for the session in textual format. It includes information about the test session’s desired capabilities and detailed information about every request and response. You can view all the steps executed in the test and troubleshoot errors for any failed steps. Learn more about text logs

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X GET "https://api-cloud.browserstack.com/app-automate/builds/g0726012b6rb0a4c79122d6048c7b8767677ad61/sessions/22dbfb187486090d974a11ac91t65722988e0705/logs"
  • buildID* String

    The build ID of the build to which the session belongs to.

  • sessionID* String

    The session ID of the session.

Response Attributes 200 OK text/plain

Response

2020-9-15 19:20:25:33 SESSION_SETUP_TIME {"initialising_device":5186.999999999999}
2020-9-15 19:20:25:33 SESSION_SETUP_TIME {"downloading_app":1436,"installing_app":4059,"setting_up_appium":6726,"setting_up_network_connection":592}
2020-9-15 19:20:30:736 SESSION_SETUP_TIME {"launching_app":5702}
2020-9-15 19:20:30:738 REQUEST [2020-9-15 19:20:30:738] POST /session {"desiredCapabilities":{"app":"LoginApp" "browserstack.appium_version":"1.18.0","os_version":"9.0","project":"SampleProject","build":"SampleBuild","name":"login_test","platformName":"Android","device":"OnePlus 6T","browserstack.debug":true, "detected_language":"selenium/3.141.59 (java mac)","new_bucketing":true}}
...
2020-9-15 19:20:30:738 START_SESSION 
2020-9-15 19:20:30:739 REQUEST [2020-9-15 19:20:30:739] GET /session/44abfb187486290d974a11ac78245722988e0705
2020-9-15 19:20:30:739 RESPONSE {"value":{"platform":"ANDROID","webStorageEnabled":false,"takesScreenshot":true,"javascriptEnabled":true,"databaseEnabled":false,"networkConnectionEnabled":true,"locationContextEnabled":false,"warnings":{},"systemPort":8205,"orientation":"PORTRAIT","udid":"e6b85abe","chromedriverPort":18085,"noReset":true,"os_version":"9.0","platformName":"Android","device":"oneplus 6t","browserstack.is_hub_canary":"false","acceptSslCert":false,"detected_language":"selenium/3.141.59 (java mac)","new_bucketing":true,"osVersion":"9.0","deviceName":"e6b85abe","sessionName":"test2","buildName":"Build2","projectName":"SampleProject"...}
...
2020-9-15 19:20:48:247 STOP_SESSION {"status":0,"sessionId":"44abfb187486290d974a11ac78245722988e0705","value":{"message":"CLIENT_STOPPED_SESSION"},"errorStack":{}}

The response will be text/plain logs comprising the details of each request and response in the session execution.

Get device logs

GET /app-automate/builds/{buildID}/sessions/{sessionID}/devicelogs

Access the device logs for your session. These are system logs specific to your application generated by the OS(Android/iOS) and can be helful for debugging any application crashes during test execution. Learn more about device logs

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X GET "https://api-cloud.browserstack.com/app-automate/builds/g0726012b6rb0a4c79122d6048c7b8767677ad61/sessions/22dbfb187486090d974a11ac91t65722988e0705/devicelogs"
  • buildID* String

    The build ID of the build to which the session belongs to.

  • sessionID* String

    The session ID of the session.

Response Attributes 200 OK text/plain

Response

09-08 19:20:41.766 E/Zygote  ( 1870): accessInfo : 0
09-08 19:20:41.891 I/art     ( 1870): Rejecting re-init on previously-failed class java.lang.Class<androidx.core.view.ViewCompat$2>: java.lang.NoClassDefFoundError: Failed resolution of: Landroid/view/View$OnUnhandledKeyEventListener;
...
09-08 19:21:00.106 I/art     ( 5098):   at void android.os.Handler.dispatchMessage(android.os.Message) (Handler.java:102)
09-08 19:21:00.106 I/art     ( 5098):   at void android.os.Looper.loop() (Looper.java:154)
09-08 19:21:00.106 I/art     ( 5098):   at void android.app.ActivityThread.main(java.lang.String[]) (ActivityThread.java:6776)
09-08 19:21:00.106 I/art     ( 5098):   at java.lang.Object java.lang.reflect.Method.invoke!(java.lang.Object, java.lang.Object[]) (Method.java:-2)
09-08 19:21:00.106 I/art     ( 5098):   at void com.android.internal.os.ZygoteInit$MethodAndArgsCaller.run() (ZygoteInit.java:1520)
09-08 19:21:00.106 I/art     ( 5098):   at void com.android.internal.os.ZygoteInit.main(java.lang.String[]) (ZygoteInit.java:1410)
09-08 19:21:00.106 I/art     ( 5098): Caused by: java.lang.ClassNotFoundException: Did nott find class "android.view.View$OnUnhandledKeyEventListener" on path: DexPathList[[zip file "/data/app/com.sample.appupgrade-2/base.apk"],nativeLibraryDirectories=[/data/app/com.sample.appupgrade-2/lib/arm64, /system/lib64, /vendor/lib64]]
...

The response will be text/plain logs comprising the details of session execution on the device.

Get Appium logs

GET /app-automate/builds/{buildID}/sessions/{sessionID}/appiumlogs

Access the Appium logs for your session. These are logs generated by the Appium server and contain the details about your each Appium command execution in the test session. You can troubleshoot any errors in case your test session failed. Learn more about Appium logs

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X GET "https://api-cloud.browserstack.com/app-automate/builds/g0726012b6rb0a4c79122d6048c7b8767677ad61/sessions/22dbfb187486090d974a11ac91t65722988e0705/appiumlogs"
  • buildID* String

    The build ID of the build to which the session belongs to.

  • sessionID* String

    The session ID of the session.

Response Attributes 200 OK text/plain

Response

2020-09-15 19:20:25:032 - [HTTP] --> POST /wd/hub/session
2020-09-15 19:20:25:032 - [HTTP] {"desiredCapabilities":{"os_version":"9.0","platformName":"Android","device":"oneplus 6t","acceptSslCert":false,"osVersion":"9.0","deviceName":"Android","sessionName":"test_login","buildName":"SampleBuild","projectName":"SampleProject"......}
...
2020-09-15 19:20:25:586 - [BaseDriver] Session created with session id: 7da24049-bde6-46f0-9419-ecaaeb36d5c8
2020-09-15 19:20:25:587 - [UiAutomator2] Starting 'com.sample.loginapplication' directly on the device
2020-09-15 19:20:25:593 - [ADB] Cannot sort build-tools folders ["19.1.0","29.0.2","android-4.4.2"] by semantic version names.
2020-09-15 19:20:25:593 - [ADB] Falling back to sorting by modification date. Original error: Invalid Version: android-4.4.2
2020-09-15 19:20:25:602 - [debug] [ADB] Trying to find a connected android device
2020-09-15 19:20:25:603 - [debug] [ADB] Getting connected devices
2020-09-15 19:20:25:613 - [AndroidDriver] Using device: e6b85abe
2020-09-15 19:20:25:615 - [ADB] Using 'adb' from '/usr/local/.browserstack/android-sdk/platform-tools/adb'
2020-09-15 19:20:25:615 - [debug] [ADB] Running '/usr/local/.browserstack/android-sdk/platform-tools/adb -P 5037 start-server'
2020-09-15 19:20:25:624 - [debug] [ADB] Setting device id to e6b85abe
2020-09-15 19:20:25:624 - [debug] [ADB] Running '/usr/local/.browserstack/android-sdk/platform-tools/adb -P 5037 -s e6b85abe shell getprop ro.build.version.sdk'
...
2020-09-15 19:20:31:303 - [HTTP] --> POST /wd/hub/session/7da24049-bde6-46f0-9419-ecaaeb36d5c8/element
2020-09-15 19:20:31:303 - [HTTP] {"using":"id","value":"com.sample.loginapplication:id/editText"}
2020-09-15 19:20:31:305 - [debug] [MJSONWP (7da24049)] Calling AppiumDriver.findElement() with args: ["id","com.sample.loginapplication:id/editText","7da24049-bde6-46f0-9419-ecaaeb36d5c8"]
...

The response will be text/plain logs comprising the details of session execution on the device.

Get network logs

GET /app-automate/builds/{buildID}/sessions/{sessionID}/networklogs

Access the network logs for your session. These logs capture network data such as network traffic, latency, HTTP requests/responses in the HAR (HTTP Archive) format. You can identify any performance bottlenecks or debug failed REST API responses. Network logs are disabled by default. Learn more about Network logs

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X GET "https://api-cloud.browserstack.com/app-automate/builds/g0726012b6rb0a4c79122d6048c7b8767677ad61/sessions/22dbfb187486090d974a11ac91t65722988e0705/networklogs"
  • buildID* String

    The build ID of the build to which the session belongs to.

  • sessionID* String

    The session ID of the session.

Response Attributes 200 OK text/plain

Response

{
    "log": {
        "version": "1.2",
        "creator": {
        "name": "mitmproxy har_dump",
        "version": "0.1",
        "comment": "mitmproxy version mitmproxy 4.0.4"
        },
        "entries": 
        [
            {
                "startedDateTime": "2020-09-16T13:56:43.127935+00:00",
                "time": 676,
                "request": {
                "method": "POST",
                "url": "https://open.oneplus.net/oauth/token",
                "httpVersion": "HTTP/1.1",
                "cookies": [],
                "headers": [
                    {
                    "name": "Content-Type",
                    "value": "application/x-www-form-urlencoded; charset=UTF-8"
                    },
                    {..}]
            },
            {...}
        ]
    }
}            

The response will be text/plain logs comprising the details of network traffic during session execution on the device.

Get app profiling data

GET /app-automate/builds/{buildID}/sessions/{sessionID}/appprofiling

Access the app profiling logs to view the resource consumption(CPU, memory, battery, and network) by your app on the device. The logs are only available for Android. Learn more about App profiling

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X GET "https://api-cloud.browserstack.com/app-automate/builds/g0726012b6rb0a4c79122d6048c7b8767677ad61/sessions/22dbfb187486090d974a11ac91t65722988e0705/appprofiling"
  • buildID* String

    The build ID of the build to which the session belongs to.

  • sessionID* String

    The session ID of the session.

Response Attributes 200 OK application/json

Response

[
    {
        "ts": 1600264609,
        "cpu": 35,
        "mem": 5633,
        "mema": 3063,
        "batt": 100,
        "temp": 22
    },
    {...}
]         
  • ts Integer

    Epoch time.

  • cpu Integer

    Percentage of CPU utilisation of overall device.

  • mem Integer

    RAM utilisation of overall device in MB.

  • mema Integer

    RAM available in device in MB.

  • batt Integer

    Battery percentage.

  • temp Integer

    Temperature of device in Celsius.

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






Thank you for your valuable feedback