Sauce Connect API Endpoints

Use the Sauce Connect API methods to monitor and clean up your active proxy tunnels.

To download Sauce Connect, see Sauce Connect Installation.

Refer to Getting Started for Authentication and Server information.

What You'll Need

A Sauce Labs account (Log in or sign up for a free trial license).
Your Sauce Labs Username and Access Key.

Get Tunnels for a User

GET /rest/v1/{username}/tunnels

Returns Tunnel IDs or Tunnels Info for any currently running tunnels launched by or shared with the specified user. It also allows to filter tunnels using an optional "filter" parameter that may take the following values:

filter=v2alpha - a response will contain only tunnels that were started with --vm-version v2alpha.
filter=one_per_pool - a response will contain only one (arbitrary) tunnel per tunnel pool.

Parameters

`username`	\| PATH \| REQUIRED \| STRING \| The authentication username of the user whose tunnels you are requesting.
`full`	\| QUERY \| OPTIONAL \| BOOLEAN \| Set to `true` to return all the tunnels info and not just IDs. Defaults to `false`.
`all`	\| QUERY \| OPTIONAL \| BOOLEAN \| Set to `true` to return the tunnels IDs/info for all the tunnels shared with the specified user. If this option is set, the response type would be a dictionary mapping user name to a list of tunnels. Defaults to `false`.
`filter`	\| QUERY \| OPTIONAL \| STRING \| Predefined filter name that can be used to filter out the tunnels. Currently the following filters are supported: `one_per_pool`, `v2alpha`.

US-West
US-East
EU-Central

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-west-1.saucelabs.com/rest/v1/jim.smith/tunnels' \
--header 'Content-Type: application/json' | json_pp

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-east-1.saucelabs.com/rest/v1/jim.smith/tunnels' \
--header 'Content-Type: application/json' | json_pp

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.eu-central-1.saucelabs.com/rest/v1/jim.smith/tunnels' \
--header 'Content-Type: application/json' | json_pp

Responses

`200`	Success.
`404`	Not found.

Sample Response to the default request
['28e7c8133ede4588a891666dd35af1f8']

Sample Response to the request with an optional parameter full=true
[
    {
        "owner": "jim.smith",
        "team_ids": [...],
        "creation_time": 1618345938,
        "domain_names": null,
        "owner": "jim.smith",
        "id": "28e7c8133ede4588a891666dd35af1f8",
        "extra_info": "{…}",
        …
        "tunnel_identifier": "jim.smith_tunnel_id"
    }
]

Sample Response to the request with an optional parameter all=true
{
    "jim.smith": [
        "28e7c8133ede4588a891666dd35af1f8"
    ]
}

Sample Response to the request with all=true&full=true
{
    "jim.smith": [
      {
          "owner": "jim.smith",
          "team_ids": [...],
          "creation_time": 1618345938,
          "domain_names": null,
          "owner": "jim.smith",
          "id": "28e7c8133ede4588a891666dd35af1f8",
          "extra_info": "{…}",
          …
          "tunnel_identifier": "jim.smith_tunnel_id"
      }
    ]
}

Get Tunnel Information

GET /rest/v1/{username}/tunnels/{tunnel_id}

Returns information about the specified tunnel.

Parameters

username

| PATH | REQUIRED | STRING |

The authentication username of the owner of the requested tunnel.

tunnel_id

| PATH | REQUIRED | STRING |

The unique identifier of the requested tunnel.

US-West
US-East
EU-Central

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-west-1.saucelabs.com/rest/v1/jim.smith/tunnels/28e7c8133ede4588a891666dd35af1f8' \
--header 'Content-Type: application/json' | json_pp

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-east-1.saucelabs.com/rest/v1/jim.smith/tunnels/28e7c8133ede4588a891666dd35af1f8' \
--header 'Content-Type: application/json' | json_pp

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.eu-central-1.saucelabs.com/rest/v1/jim.smith/tunnels/28e7c8133ede4588a891666dd35af1f8' \
--header 'Content-Type: application/json' | json_pp

Responses

`200`	Success.
`404`	Not found.

Sample Response
{
    "owner": "jim.smith",
    "team_ids": [...],
    "creation_time": 1618345938,
    "domain_names": null,
    "id": "28e7c8133ede4588a891666dd35af1f8",
    "extra_info": "{…}",
    "direct_domains": null,
    "vm_version": "",
    "no_ssl_bump_domains": null,
    "shared_tunnel": false,
    "metadata": {...},
    "status": "running",
    "is_ready": true,
    "shutdown_reason" : null,
    "shutdown_time" : null,
    "user_shutdown": null,
    "host": "maki3429.miso.saucelabs.com",
    "ip_address": null,
    "last_connected": 1618346660,
    "launch_time": 1618345940,
    "tunnel_identifier": "jim.smith_tunnel_id"
}

Get Tunnel Version Downloads

GET /rest/v1/public/tunnels/info/versions

Returns tunnel version download information.

Parameters

client_version

| QUERY | OPTIONAL | STRING |

Returns download information for the specified Sauce Connect client version (For example, 4.7.1).

client_host

| QUERY | OPTIONAL | STRING |

Returns download information for the Sauce Connect Proxy version with the specified host OS and CPU Architecture (For example, darwin-amd64).

all

| QUERY | OPTIONAL | BOOLEAN |

Set to `true` to return download information for all available Sauce Connect Proxy versions. Defaults to `false`.

US-West
US-East
EU-Central

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-west-1.saucelabs.com/rest/v1/public/tunnels/info/versions' | json_pp

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-east-1.saucelabs.com/rest/v1/public/tunnels/info/versions' | json_pp

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.eu-central-1.saucelabs.com/rest/v1/public/tunnels/info/versions' | json_pp

Responses

`200`	Success.
`404`	Not found.

Sample Response to the default request
{
   "downloads" : {
      "linux" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.1-linux.tar.gz",
         "sha1" : "<hash>"
      },
      "linux-arm64" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.1-linux-arm64.tar.gz",
         "sha1" : "<hash>"
      },
      "osx" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.1-osx.zip",
         "sha1" : "<hash>"
      },
      "win32" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.1-win32.zip",
         "sha1" : "<hash>"
      }
   },
   "info_url" : "https://docs.saucelabs.com/secure-connections/sauce-connect/installation",
   "latest_version" : "4.9.1",
   "warning" : [
      "Client host platform is not specified, the download URL cannot be determined"
   ]
}

Sample Response to the request with an optional parameter all=true
{
   "all_downloads" : {
      "4.7.0" : {
         "linux" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.7.0-linux.tar.gz",
            "sha1" : "<hash>"
         },
         "osx" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.7.0-osx.zip",
            "sha1" : "<hash>"
         }
      },
      "4.7.1" : {
         "linux" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.7.1-linux.tar.gz",
            "sha1" : "<hash>"
         },
         "linux-arm64" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.7.1-linux-arm64.tar.gz",
            "sha1" : "<hash>"
         },
         "osx" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.7.1-osx.zip",
            "sha1" : "<hash>"
         },
         "win32" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.7.1-win32.zip",
            "sha1" : "<hash>"
         }
      },
      "4.8.0" : {
         "linux" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.8.0-linux.tar.gz",
            "sha1" : "<hash>"
         },
         "linux-arm64" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.8.0-linux-arm64.tar.gz",
            "sha1" : "<hash>"
         },
         "osx" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.8.0-osx.zip",
            "sha1" : "<hash>"
         },
         "win32" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.8.0-win32.zip",
            "sha1" : "<hash>"
         }
      },
      "4.8.1" : {
         "linux" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.8.1-linux.tar.gz",
            "sha1" : "<hash>"
         },
         "linux-arm64" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.8.1-linux-arm64.tar.gz",
            "sha1" : "<hash>"
         },
         "osx" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.8.1-osx.zip",
            "sha1" : "<hash>"
         },
         "win32" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.8.1-win32.zip",
            "sha1" : "<hash>"
         }
      },
      "4.8.2" : {
         "linux" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.8.2-linux.tar.gz",
            "sha1" : "<hash>"
         },
         "linux-arm64" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.8.2-linux-arm64.tar.gz",
            "sha1" : "<hash>"
         },
         "osx" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.8.2-osx.zip",
            "sha1" : "<hash>"
         },
         "win32" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.8.2-win32.zip",
            "sha1" : "<hash>"
         }
      },
      "4.9.0" : {
         "linux" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.9.0-linux.tar.gz",
            "sha1" : "<hash>"
         },
         "linux-arm64" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.9.0-linux-arm64.tar.gz",
            "sha1" : "<hash>"
         },
         "osx" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.9.0-osx.zip",
            "sha1" : "<hash>"
         },
         "win32" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.9.0-win32.zip",
            "sha1" : "<hash>"
         }
      },
      "4.9.1" : {
         "linux" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.9.1-linux.tar.gz",
            "sha1" : "<hash>"
         },
         "linux-arm64" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.9.1-linux-arm64.tar.gz",
            "sha1" : "<hash>"
         },
         "osx" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.9.1-osx.zip",
            "sha1" : "<hash>"
         },
         "win32" : {
            "download_url" : "https://saucelabs.com/downloads/sc-4.9.1-win32.zip",
            "sha1" : "<hash>"
         }
      }
   },
   "downloads" : {
      "linux" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.1-linux.tar.gz",
         "sha1" : "<hash>"
      },
      "linux-arm64" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.1-linux-arm64.tar.gz",
         "sha1" : "<hash>"
      },
      "osx" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.1-osx.zip",
         "sha1" : "<hash>"
      },
      "win32" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.1-win32.zip",
         "sha1" : "<hash>"
      }
   },
   "info_url" : "https://docs.saucelabs.com/secure-connections/sauce-connect/installation",
   "latest_version" : "4.9.1",
   "warning" : [
      "Client host platform is not specified, the download URL cannot be determined"
   ]
}

Sample Response to the request with an optional parameter client_host=darwin-amd64
{
   "download_url" : "https://saucelabs.com/downloads/sc-4.9.1-osx.zip",
   "downloads" : {
      "linux" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.1-linux.tar.gz",
         "sha1" : "<hash>"
      },
      "linux-arm64" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.1-linux-arm64.tar.gz",
         "sha1" : "<hash>"
      },
      "osx" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.1-osx.zip",
         "sha1" : "<hash>"
      },
      "win32" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.1-win32.zip",
         "sha1" : "<hash>"
      }
   },
   "info_url" : "https://docs.saucelabs.com/secure-connections/sauce-connect/installation",
   "latest_version" : "4.9.1",
   "sha1" : "<hash>"
}

Sample Response to the request with an optional parameter client_version=4.7.1
{
   "client_version" : "4.7.1",
   "downloads" : {
      "linux" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.1-linux.tar.gz",
         "sha1" : "<hash>"
      },
      "linux-arm64" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.1-linux-arm64.tar.gz",
         "sha1" : "<hash>"
      },
      "osx" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.1-osx.zip",
         "sha1" : "<hash>"
      },
      "win32" : {
         "download_url" : "https://saucelabs.com/downloads/sc-4.9.1-win32.zip",
         "sha1" : "<hash>"
      }
   },
   "info_url" : "https://docs.saucelabs.com/secure-connections/sauce-connect/installation",
   "latest_version" : "4.9.1",
   "status" : "UPGRADE",
   "warning" : [
      "Client host platform is not specified, the download URL cannot be determined"
   ]
}

Get Current Jobs for a Tunnel

GET /rest/v1/{username}/tunnels/{tunnel_id}/num_jobs

Returns the number of currently running jobs for the specified tunnel.

Parameters

username

| PATH | REQUIRED | STRING |

The authentication username of the user whose tunnels you are requesting.

tunnel_id

| PATH | REQUIRED | STRING |

The unique identifier of the requested tunnel.

US-West
US-East
EU-Central

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-west-1.saucelabs.com/rest/v1/jim.smith/tunnels/28e7c8133ede4588a891666dd35af1f8/num_jobs' \
--header 'Content-Type: application/json' | json_pp

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-east-1.saucelabs.com/rest/v1/jim.smith/tunnels/28e7c8133ede4588a891666dd35af1f8/num_jobs' \
--header 'Content-Type: application/json' | json_pp

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.eu-central-1.saucelabs.com/rest/v1/jim.smith/tunnels/28e7c8133ede4588a891666dd35af1f8/num_jobs' \
--header 'Content-Type: application/json' | json_pp

Responses

`200`	Success.
`404`	Not found.

Sample Response
{
    "id": "28e7c8133ede4588a891666dd35af1f8",
    "jobs_running": 1
}

Stop a Tunnel

DELETE /rest/v1/{username}/tunnels/{tunnel_id}

Shuts down the specified tunnel.

Parameters

username

| PATH | REQUIRED | STRING |

The authentication username of the user whose tunnels you are requesting.

tunnel_id

| PATH | REQUIRED | STRING |

The unique identifier of the tunnel to stop.

US-West
US-East
EU-Central

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request DELETE 'https://api.us-west-1.saucelabs.com/rest/v1/jim.smith/tunnels/28e7c8133ede4588a891666dd35af1f8' \
--header 'Content-Type: application/json' | json_pp

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request DELETE 'https://api.us-east-1.saucelabs.com/rest/v1/jim.smith/tunnels/28e7c8133ede4588a891666dd35af1f8' \
--header 'Content-Type: application/json' | json_pp

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request DELETE 'https://api.eu-central-1.saucelabs.com/rest/v1/jim.smith/tunnels/28e7c8133ede4588a891666dd35af1f8' \
--header 'Content-Type: application/json' | json_pp

Responses

`200`	Success.
`404`	Not found.

Sample Response
{
    "result": true,
    "id": "28e7c8133ede4588a891666dd35af1f8",
    "jobs_running": 0
}

What You'll Need​

Get Tunnels for a User​

Parameters​

Responses​

Get Tunnel Information​

Parameters​

Responses​

Get Tunnel Version Downloads​

Parameters​

Responses​

Get Current Jobs for a Tunnel​

Parameters​

Responses​

Stop a Tunnel​

Parameters​

Responses​

What You'll Need

Get Tunnels for a User

Parameters

Responses

Get Tunnel Information

Parameters

Responses

Get Tunnel Version Downloads

Parameters

Responses

Get Current Jobs for a Tunnel

Parameters

Responses

Stop a Tunnel

Parameters

Responses