Skip to main content

Sauce Connect API Methods

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 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
}