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. Accepted characters are A-Z, a-z, 0-9, ., -, _. All other characters are ignored. Character limit is 100.
- 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
Show 8 more
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. Note that sessions once deleted cannot be recovered.

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.

Post terminal logs

POST /app-automate/sessions/{session_id}/terminallogs

Upload terminal logs for your session using the POST method.

Request Parameters

Request

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

session_id^* String

ID of the session available on the App 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.

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.

Get app profiling data v2

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

Access the detailed app profling metrics such as installed app size, UI rendering metrics, resource consumption metrics, etc. For details, please refer to the documentation : App frontend performance testing on App Automate.

Request Parameters

Request

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

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

{
  "metadata": {
    "device": "...",
    "os_version": "...",
    "created_at": "..."
  },
  "data": {
    "units": {
      "app_size": "MB",
      "app_start_time": "ms",
      "cpu": "%",
      "mem": "MB",
      "batt": "mAh",
      "diskio": "kb",
      "networkio": "kb",
      "ui_rendering": "fps",
      "screen_load": "ms"
    },
    "org.wikipedia.alpha": {
      "status": "success",
      "detected_issues": [],
      "metrics": {
        "app_size": 20.37,
        "cpu": {
          "avg": 5.06,
          "max": 12.52,
          "cpu_usage_data": "https://api-cloud.browserstack.com/app-automate/builds/<build_id>/sessions/<session_id>/appprofiling/v2/org.wikipedia.alpha/stats/cpu_usage"
        },
        "mem": {
          "avg": 169.45,
          "max": 243.57,
          "mem_usage_data": "https://api-cloud.browserstack.com/app-automate/builds/<build_id>/sessions/<session_id>/appprofiling/v2/org.wikipedia.alpha/stats/mem_usage"
        },
        "batt": {
          "total_batt_usage": 1.712,
          "total_batt_usage_pct": 0.034,
          "batt_usage_data": "https://api-cloud.browserstack.com/app-automate/builds/<build_id>/sessions/<session_id>/appprofiling/v2/org.wikipedia.alpha/stats/batt_usage"
        },
        "diskio": {
          "total_reads": 260,
          "total_writes": 15390,
          "disk_usage_data": "https://api-cloud.browserstack.com/app-automate/builds/<build_id>/sessions/<session_id>/appprofiling/v2/org.wikipedia.alpha/stats/disk_usage"
        },
        "networkio": {
          "total_upload": 41.8,
          "total_download": 760.05,
          "network_usage_data": "https://api-cloud.browserstack.com/app-automate/builds/<build_id>/sessions/<session_id>/appprofiling/v2/org.wikipedia.alpha/stats/network_usage"
        },
        "ui_rendering": {
          "slow_frames_pct": 5.63,
          "frozen_frames_pct": 0,
          "num_anrs": 0,
          "fps_data": "https://api-cloud.browserstack.com/app-automate/builds/<build_id>/sessions/<session_id>/appprofiling/v2/org.wikipedia.alpha/stats/fps"
        },
        "screen_load": {
          "activity_load_time": [
            {
              "name": "org.wikipedia.alpha/org.wikipedia.main.MainActivity",
              "load_time_data": [
                {
                  "time_offset_ms": 4386,
                  "load_time": 295
                }
              ]
            }
          ]
        }
      }
    }
  }
}        

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

Sessions

Get session details

Request Parameters

sessionID* String

Response Attributes 200 OK application/json

automation_session Object

name String

duration String

os String

os_version String

browser_version String

device String

status String

reason String

build_name String

project_name String

logs String

public_url String

appium_logs_url String

video_url String

device_logs_url String

app_details Object

app_url String

app_name String

app_version String

app_custom_id String

uploaded_at String

Update session status

Request Parameters

sessionID* String

status* String

reason String

Response Attributes 200 OK application/json

name String

duration Integer

os String

os_version String

browser_version String

browser String

device String

status String

hashed_id String

reason String

build_name String

project_name String

test_priority String

Delete a session

Request Parameters

sessionID* String

Response Attributes 200 OK application/json

status String

message String

Get text logs

Request Parameters

buildID* String

sessionID* String

Response Attributes 200 OK text/plain

Get device logs

Request Parameters

buildID* String

sessionID* String

Response Attributes 200 OK text/plain

Get Appium logs

Request Parameters

buildID* String

sessionID* String

Response Attributes 200 OK text/plain

Get network logs

Request Parameters

buildID* String

sessionID* String

Response Attributes 200 OK text/plain

Post terminal logs

Request Parameters

session_id* String

file* Path

Response Attributes 200 OK JSON

status String

message String

Get app profiling data

sessionID^* String

Response Attributes `200 OK` `application/json`

sessionID^* String

status^* String

Response Attributes `200 OK` `application/json`

sessionID^* String

Response Attributes `200 OK` `application/json`

buildID^* String

sessionID^* String

Response Attributes `200 OK` `text/plain`

buildID^* String

sessionID^* String

Response Attributes `200 OK` `text/plain`

buildID^* String

sessionID^* String

Response Attributes `200 OK` `text/plain`

buildID^* String

sessionID^* String

Response Attributes `200 OK` `text/plain`

session_id^* String

file^* Path

Response Attributes `200 OK` `JSON`

buildID^* String

sessionID^* String

Response Attributes `200 OK` `application/json`

buildID^* String

sessionID^* String

Response Attributes `200 OK` `application/json`