Skip to main content

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

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.

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

Responses

200Success.
404Not 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.

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

Responses

200Success.
404Not 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`.

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

Responses

200Success.
404Not found.
Sample Response to the default request
{
"downloads" : {
"linux" : {
"download_url" : "https://saucelabs.com/downloads/sc-4.9.2-linux.tar.gz",
"sha1" : "<hash>"
},
"linux-arm64" : {
"download_url" : "https://saucelabs.com/downloads/sc-4.9.2-linux-arm64.tar.gz",
"sha1" : "<hash>"
},
"osx" : {
"download_url" : "https://saucelabs.com/downloads/sc-4.9.2-osx.zip",
"sha1" : "<hash>"
},
"win32" : {
"download_url" : "https://saucelabs.com/downloads/sc-4.9.2-win32.zip",
"sha1" : "<hash>"
}
},
"info_url" : "https://docs.saucelabs.com/secure-connections/sauce-connect/installation",
"latest_version" : "4.9.2",
"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>"
}
},
"4.9.2" : {
"linux" : {
"download_url" : "https://saucelabs.com/downloads/sc-4.9.2-linux.tar.gz",
"sha1" : "<hash>"
},
"linux-arm64" : {
"download_url" : "https://saucelabs.com/downloads/sc-4.9.2-linux-arm64.tar.gz",
"sha1" : "<hash>"
},
"win32" : {
"download_url" : "https://saucelabs.com/downloads/sc-4.9.2-win32.zip",
"sha1" : "<hash>"
}
}
},
"downloads" : {
"linux" : {
"download_url" : "https://saucelabs.com/downloads/sc-4.9.2-linux.tar.gz",
"sha1" : "<hash>"
},
"linux-arm64" : {
"download_url" : "https://saucelabs.com/downloads/sc-4.9.2-linux-arm64.tar.gz",
"sha1" : "<hash>"
},
"win32" : {
"download_url" : "https://saucelabs.com/downloads/sc-4.9.2-win32.zip",
"sha1" : "<hash>"
}
},
"info_url" : "https://docs.saucelabs.com/secure-connections/sauce-connect/installation",
"latest_version" : "4.9.2",
"warning" : [
"Client host platform is not specified, the download URL cannot be determined"
]
}
Sample Response to the request with an optional parameter client_host=linux
{
"download_url" : "https://saucelabs.com/downloads/sc-4.9.2-linux.tar.gz",
"downloads" : {
"linux" : {
"download_url" : "https://saucelabs.com/downloads/sc-4.9.2-linux.tar.gz",
"sha1" : "<hash>"
},
"linux-arm64" : {
"download_url" : "https://saucelabs.com/downloads/sc-4.9.2-linux-arm64.tar.gz",
"sha1" : "<hash>"
},
"win32" : {
"download_url" : "https://saucelabs.com/downloads/sc-4.9.2-win32.zip",
"sha1" : "<hash>"
}
},
"info_url" : "https://docs.saucelabs.com/secure-connections/sauce-connect/installation",
"latest_version" : "4.9.2",
"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.2-linux.tar.gz",
"sha1" : "<hash>"
},
"linux-arm64" : {
"download_url" : "https://saucelabs.com/downloads/sc-4.9.2-linux-arm64.tar.gz",
"sha1" : "<hash>"
},
"win32" : {
"download_url" : "https://saucelabs.com/downloads/sc-4.9.2-win32.zip",
"sha1" : "<hash>"
}
},
"info_url" : "https://docs.saucelabs.com/secure-connections/sauce-connect/installation",
"latest_version" : "4.9.2",
"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.

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

Responses

200Success.
404Not 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.

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

Responses

200Success.
404Not found.
Sample Response
{
"result": true,
"id": "28e7c8133ede4588a891666dd35af1f8",
"jobs_running": 0
}