Introduction

If you are using your account to test multiple applications or builds, we recommend setting up a separate Local Testing connection for each. Local Testing API helps manage and debug these connections.

Enabling Local Testing API

Establish local testing connections using ‘–enable-logging-for-api’ parameter (more info here) - this enables Local Testing API. Now, you can use the API to manage and disconnect binary instances as follows:

Get a list of active binary instances

Run the following command through your command-line interface:

Usage: GET /local/<version>/list

Command Line

 curl -x GET https://www.browserstack.com/local/v1/list?auth_token=YOUR_ACCESS_KEY&last=5&state=running

Parameters	Value
version The version of the API to be used.	Current version is v1
last The number of recent binary instances to be listed.	Default:20, Maximum value: 100
state Configures to list whether all binary instances or currently running instances.	all, running default: running

Note: On success, you will get a response code 200

Response

 {
    "api_version": "v1",
    "meta_data": { "params": {}}
    "instances": [
      {
        "lastActiveOn": "2016-07-19 14:19:43 +0000",
        "localIdentifier": "",
        "email": "john@browserstack.com",
        "commandLineParams": "--key YOUR_ACCESS_KEY --enable-logging-for-api",
        "public-IP": "8.8.4.4",
        "hostname": "my-local-box",
        "endTime": null,
        "disconnectReason": null,
        "startTime": "2016-07-19 14:12:58 +0000",
        "privateIP": ["127.0.0.1", "10.100.100.1", ….],
        "id": "QUERTY1"
      },
     {
        "lastActiveOn": "2016-07-19 14:19:43 +0000",
        "localIdentifier": "test-1",
        "email": "john@browserstack.com",
        "commandLineParams": "--key YOUR_ACCESS_KEY --enable-logging-for-api --local-identifier test-1",
        "public-IP": "8.8.4.4",
        "hostname": "my-local-box",
        "endTime": null,
        "disconnectReason": null,
        "startTime": "2016-07-19 14:12:58 +0000",
        "privateIP": ["127.0.0.1", "10.100.100.1", ….],
        "id": "QUERTY2"
      },
    ...
      ]
  }

Retrieve details of an active binary instance using its ID

Usage: GET /local/<version>/<id>

Command Line

 https://www.browserstack.com/local/v1/QUERTY1?auth_token=YOUR_ACCESS_KEY

Parameters	Value
version The version of the API to be used.	Current version is v1
id The Binary id that needs to be retrieved	String value

Note: On success, you will get a response code 200

Response

  {
    "api_version": "v1",
    "meta_data": { "params": {}}
    "instances": [
      {
        "lastActiveOn": "2016-07-19 14:19:43 +0000",
        "localIdentifier": "",
        "email": "john@browserstack.com",
        "commandLineParams": "YOUR_ACCESS_KEY --enable-logging-for-api",
        "public-IP": "8.8.4.4",
        "hostname": "my-local-box",
        "endTime": null,
        "disconnectReason": null,
        "startTime": "2016-07-19 14:12:58 +0000",
        "privateIP": ["127.0.0.1", "10.100.100.1", ….],
        "id": "QUERTY1"
      }
      ]
  }

Errors:

Response code/Description	Response message
401 Authentication failed due to incorrect token.	{“error”: “Invalid auth token”}
422 The ID requested for is incorrect.	{“error”: “Incorrect id”}
503 There was an exception.	{“error”: “Something went wrong, please try again after sometime”}

Disconnect an active binary using its ID

Usage: DELETE /local/<version>/<id>

Command Line

 curl -X DELETE "https://www.browserstack.com/local/v1/QUERTY1?auth_token=YOUR_ACCESS_KEY

Parameters	Value
version The version of the API to be used.	Current version is v1
id The Binary id that needs to be retrieved	String value

Note: On success, you will get a response code 200

Response

{
    "api_version": "v1",
    "meta_data": { "params": {}},
    "message": "QUERTY1 successfully disconnected
                " / "QUERTY1 was already disconnected"
}

Errors:

Response code/Description	Response message
401 Authentication failed due to incorrect token.	{“error”: “Invalid auth token”}
422 The ID requested for is incorrect.	{“error”: “Incorrect id”}
500 There was an exception.	{“error”: “Failed to disconnect, please try again. Please contact support@browserstack.com if the issue is persistent.”}

Note

Requests to these APIs are throttled at 20 requests for 5 minutes
For these APIs to include binaries in results, the binary should have been started with ‘enable-logging-for-api’ parameter. Example: ./BrowserStackLocal --key YOUR_ACCESS_KEY --enable-logging-for-api <other_params>
In case the ‘enable-logging-for-api’ parameter is not used the response would have empty instance. However the instance would still be recorded in our database without storing any sensitive information.

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

Is this page helping you?

Yes

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!