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
}