Jobs API Methods
The Jobs API methods allow you to review and edit the metadata associated with the tests you are running on Sauce Labs. You can also stop tests, delete jobs, and filter lists of jobs by a variety of attributes, such as owner, time period, build, or environment.
These calls are specific to jobs running in simulation. For methods related to Real Device testing, see Real Device API Methods.
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
Jobs Methods
The set of methods defined in this section are applicable to tests that are not associated with builds.
Get Jobs
GET /rest/v1/{username}/jobs
Get a list of recent jobs run by the specified user.
Parameters
username | | PATH | REQUIRED | STRING | The username of the Sauce Labs user whose jobs you are looking up. You can look up Sauce Labs users in your organization using the Lookup Users endpoint. |
limit | | QUERY | OPTIONAL | INTEGER | The maximum number of jobs to return. |
skip | | QUERY | OPTIONAL | INTEGER | Returns only the jobs beginning after this index number. |
from | | QUERY | OPTIONAL | DATE-TIME | Return only jobs that ran on or after this Unix timestamp. |
to | | QUERY | OPTIONAL | DATE-TIME | Return only jobs that ran on or before this Unix timestamp. |
format | | QUERY | OPTIONAL | STRING | The format in which you want the results. Valid values are |
- United States
- Europe
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-west-1.saucelabs.com/rest/v1/jsmith/jobs?from=1616262316&to=1618940716' | json_pp
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.eu-central-1.saucelabs.com/rest/v1/jsmith/jobs?from=1616262316&to=1618940716' | json_pp
Responses
200 | Success. | |
404 | Not found. |
[
{
"status": "complete",
"base_config": {
"username": "jsmith",
"name": "demoPageTitle",
"accesskey": "******",
"platform": "macOS 10.12",
"browserName": "safari",
"version": "11.0",
"extendedDebugging": true,
"capturePerformance": true
},
"command_counts": {
"All": 4,
"Error": 2
},
"deletion_time": null,
"url": null,
"org_id": "******",
"creation_time": 1618283133,
"id": "3bad2bfb82404fb184c74716b668d65f",
"team_id": "******",
"performance_enabled": true,
"assigned_tunnel_id": null,
"container": false,
"group_id": "******",
"public": "team",
"breakpointed": null
},
{...},
Get Job Details
GET /rest/v1/{username}/jobs/{job_id}
Get detailed information about a specific job.
Parameters
username | | PATH | REQUIRED | STRING | The username of the Sauce Labs user whose jobs you are looking up. You can look up Sauce Labs users in your organization using the Lookup Users endpoint. |
job_id | | PATH | REQUIRED | STRING | The Sauce Labs identifier of the job you are looking up. You can look up job IDs using the Get Jobs endpoint. |
- United States
- Europe
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-west-1.saucelabs.com/rest/v1/jsmith/jobs/eed5eb4999d840f89f67f8b6d60a2da3' | json_pp
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.eu-central-1.saucelabs.com/rest/v1/jsmith/jobs/eed5eb4999d840f89f67f8b6d60a2da3' | json_pp
Responses
200 | Success. | |
404 | Not found. |
{
"browser_short_version": "89",
"video_url": "https://assets.saucelabs.com/jobs/eed5eb4999d840f89f67f8b6d60a2da3/video.mp4",
"creation_time": 1618860861,
"custom-data": null,
"browser_version": "89.0.4389.72",
"owner": "jsmith",
"automation_backend": "cypress",
"id": "eed5eb4999d840f89f67f8b6d60a2da3",
"collects_automator_log": false,
"record_screenshots": true,
"record_video": true,
"build": "Release",
"passed": true,
"public": "team",
"assigned_tunnel_id": "***",
"status": "complete",
"log_url": "https://assets.saucelabs.com/jobs/eed5eb4999d840f89f67f8b6d60a2da3/selenium-server.log",
"start_time": 1618860862,
"proxied": true,
"modification_time": 1618860985,
"tags": [
"e2e",
"release team",
"other tag"
],
"name": "Testing Cypress Support - login test",
"commands_not_successful": 0,
"consolidated_status": "passed",
"selenium_version": null,
"manual": false,
"end_time": 1618860985,
"error": null,
"os": "Windows 10",
"breakpointed": null,
"browser": "googlechrome"
}
Update a Job
PUT /rest/v1/{username}/jobs/{job_id}
Edit job attributes based on parameters passed in the request, including setting the status and name of the job. Any parameter for which a new value is provided in the request will replace the existing value. For example, if you provide a set of tags, they will not be added to the current tags; they will replace them, so make sure you pass the entire set you wish to assign.
This call is specific to jobs running in simulation. To update a job for real devices, use the Selenium JavaScript Executor.
Parameters
username | | PATH | REQUIRED | STRING | The username of the owner of the job you are updating. You can look up Sauce Labs users in your organization using the Lookup Users endpoint. |
job_id | | PATH | REQUIRED | STRING | The Sauce Labs identifier of the job to be updated. You can look up job IDs using the Get Jobs endpoint. |
name | | BODY | OPTIONAL | STRING | A new name for the job. |
tags | | BODY | OPTIONAL | ARRAY | The set of distinguishing tags to apply to the job. |
public | | BODY | OPTIONAL | STRING | Specifies the level of visibility permitted for the job. Valid values are:
Specify multiple roles as comma-separated values. |
passed | | BODY | OPTIONAL | BOOLEAN | Asserts whether the job passed ( |
build | | BODY | OPTIONAL | STRING | Assign the job to a build. You can specify an existing build name or create a new one. |
custom-data | | BODY | OPTIONAL | ARRAY of KEY:VALUE Pairs | Any relevant attributes you wish to add to the job details. |
- United States
- Europe
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request PUT 'https://api.us-west-1.saucelabs.com/rest/v1/walkerlj0/jobs/a2f60bf3ea5f43fa90126f82c0ba2cf6' \
--header 'Content-Type: application/json'
--data-raw '{
"name": "Cypress Training Test",
"tags": [
"e2e",
"release team",
"other tag",
"training",
"sauce-school"
],
"custom-data": {
"tcd": "true",
"editor": "nsweeney"
}
}'
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request PUT 'https://api.eu-central-1.saucelabs.com/rest/v1/walkerlj0/jobs/a2f60bf3ea5f43fa90126f82c0ba2cf6' \
--header 'Content-Type: application/json'
--data-raw '{
"name": "Cypress Training Test",
"tags": [
"e2e",
"release team",
"other tag",
"training",
"sauce-school"
],
"custom-data": {
"tcd": "true",
"editor": "nsweeney"
}
}'
Responses
200 | Success. | |
400 | Bad Request. | |
404 | Not found. |
{
"browser_short_version": "81.0",
"video_url": "https://assets.saucelabs.com/jobs/a2f60bf3ea5f43fa90126f82c0ba2cf6/video.flv",
"creation_time": 1618355254,
"custom-data": {
"tcd": "true",
"editor": "nsweeney"
},
"browser_version": "81.0.4044.138",
"owner": "walkerlj0",
"id": "a2f60bf3ea5f43fa90126f82c0ba2cf6",
"record_screenshots": true,
"record_video": true,
"build": "Release ",
"passed": false,
"public": "team",
"assigned_tunnel_id": null,
"status": "complete",
"log_url": "https://assets.saucelabs.com/jobs/a2f60bf3ea5f43fa90126f82c0ba2cf6/selenium-server.log",
"start_time": 1618355254,
"proxied": false,
"modification_time": 1618867580,
"tags": [
"e2e",
"release team",
"other tag",
"training",
"sauce-school"
],
"name": "Cypress Training Test",
"commands_not_successful": 0,
"consolidated_status": "failed",
"end_time": 1618355281,
"error": "",
"os": "saucelabs/stt-cypress-mocha-node:v6.0.2",
"breakpointed": null,
"browser": "chrome"
}
Stop a Job
PUT /rest/v1/{username}/jobs/{job_id}/stop
Get detailed information about a specific job.
Parameters
username | | PATH | REQUIRED | STRING | The username of the owner of the job to stop. You can look up Sauce Labs users in your organization using the Lookup Users endpoint. |
job_id | | PATH | REQUIRED | STRING | The Sauce Labs identifier of the job to stop. You can look up job IDs using the Get Jobs endpoint. |
- United States
- Europe
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request PUT 'https://api.us-west-1.saucelabs.com/rest/v1/nancy.sweeney/jobs/ec92ec2e200d40b8a75a4f6c06e2226f/stop' | json_pp
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request PUT 'https://api.eu-central-1.saucelabs.com/rest/v1/nancy.sweeney/jobs/ec92ec2e200d40b8a75a4f6c06e2226f/stop' | json_pp
Responses
200 | Success. | |
404 | Not found. |
{
"browser_short_version": "89",
"video_url": "https://assets.saucelabs.com/jobs/ec92ec2e200d40b8a75a4f6c06e2226f/video.mp4",
"creation_time": 1618870023,
"custom-data": null,
"browser_version": "89.0.4389.72",
"owner": "nancy.sweeney",
"id": "ec92ec2e200d40b8a75a4f6c06e2226f",
"record_screenshots": true,
"record_video": true,
"build": null,
"passed": null,
"public": "team",
"assigned_tunnel_id": null,
"status": "complete",
"log_url": "https://assets.saucelabs.com/jobs/ec92ec2e200d40b8a75a4f6c06e2226f/selenium-server.log",
"start_time": 1618870025,
"proxied": false,
"modification_time": 1618870063,
"tags": [],
"name": "Performance test for https://paypal.com (on \"Good 3G\" and 4x CPU throttling)",
"commands_not_successful": 2,
"consolidated_status": "complete",
"end_time": 1618870063,
"error": null,
"os": "Windows 10",
"breakpointed": null,
"browser": "googlechrome"
}
Delete a Job
DELETE /rest/v1/{username}/jobs/{job_id}
Delete a job and all of its assets from the Sauce Labs test history.
Parameters
job_id | | PATH | REQUIRED | STRING | The Sauce Labs identifier of the job to delete. You can look up job IDs using the Get Jobs endpoint. |
- United States
- Europe
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request DELETE 'https://api.us-west-1.saucelabs.com/rest/v1.1/jobs/a521fd8a78c4426fb10ab765ab1f6831' | json_pp
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request DELETE 'https://api.eu-central-1.saucelabs.com/rest/v1.1/jobs/a521fd8a78c4426fb10ab765ab1f6831' | json_pp
Responses
204 | No Content. | |
404 | Not found. |
No payload is returned with the successful deletion.
List Job Assets
GET /rest/v1/{username}/jobs/{job_id}/assets
Get a list of files associated with a specific test, such as the logs, video, and screenshots.
Parameters
username | | PATH | REQUIRED | STRING | The username of the owner of the job. You can look up Sauce Labs users in your organization using the Lookup Users endpoint. |
job_id | | PATH | REQUIRED | STRING | The Sauce Labs identifier of the job for which you are retrieving the asset list. You can look up job IDs using the Get Jobs endpoint. |
- United States
- Europe
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-west-1.saucelabs.com/rest/v1/nancy.sweeney/jobs/bc3d1dbd96fd4479925f2afa8efbc090/assets' | json_pp
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.eu-central-1.saucelabs.com/rest/v1/nancy.sweeney/jobs/bc3d1dbd96fd4479925f2afa8efbc090/assets' | json_pp
Responses
200 | Success. | |
404 | Not found. |
{
"automator.log": "automator.log",
"network.har": "network.har",
"video.mp4": "video.mp4",
"selenium-log": "selenium-server.log",
"performance.json": "performance.json",
"sauce-log": "log.json",
"video": "video.mp4",
"screenshots": [
"0000screenshot.png",
"0001screenshot.png",
"0002screenshot.png"
]
}
Get a Job Asset File
GET /rest/v1/{username}/jobs/{job_id}/assets/{file_name}
Retrieve one of the asset files associated with a job, such as a log file, video, or screenshot. The response contains the output of the requested file.
Parameters
username | | PATH | REQUIRED | STRING | The username of the owner of the job. You can look up Sauce Labs users in your organization using the Lookup Users endpoint. |
job_id | | PATH | REQUIRED | STRING | The Sauce Labs identifier of the job for which you are retrieving the asset list. You can look up job IDs using the Get Jobs endpoint. |
file_name | | PATH | REQUIRED | STRING | The name of the asset file you wish to download. You can look up file names using the List Job Assets endpoint. |
- United States
- Europe
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location --compressed \
--request GET 'https://api.us-west-1.saucelabs.com/rest/v1/nancy.sweeney/jobs/bc3d1dbd96fd4479925f2afa8efbc090/assets/performance.json' | json_pp
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location --compressed \
--request GET 'https://api.eu-central-1.saucelabs.com/rest/v1/nancy.sweeney/jobs/bc3d1dbd96fd4479925f2afa8efbc090/assets/performance.json' | json_pp
Responses
200 | Success. | |
404 | Not found. |
;[
{
lighthouseVersion: '6.3.0',
timestamp: 1618922245243,
loaderId: '806270ED1EF8FA367C4CDC4083079F32',
score: 0.61,
url: 'https://www.paypal.com/',
value: {
mainThreadWorkBreakdown: [
{
group: 'scriptEvaluation',
duration: 498
},
{
group: 'other',
duration: 304
},
{
group: 'styleLayout',
duration: 236
},
{
group: 'paintCompositeRender',
duration: 102
},
{
group: 'parseHTML',
duration: 24
},
{
group: 'garbageCollection',
duration: 22
},
{
group: 'scriptParseCompile',
duration: 18
}
],
diagnostics: {
numRequests: 33,
numScripts: 12,
numStylesheets: 1,
numFonts: 4,
numTasks: 266,
numTasksOver10ms: 16,
numTasksOver25ms: 7,
numTasksOver50ms: 5,
numTasksOver100ms: 2,
numTasksOver500ms: 0,
rtt: 8,
throughput: 1446875.3581661892,
maxRtt: 26,
maxServerLatency: 581,
totalByteWeight: 3646672,
totalTaskTime: 1204,
mainDocumentTransferSize: 37202
},
metrics: {
estimatedInputLatency: 19,
timeToFirstByte: 572,
serverResponseTime: 572,
domContentLoaded: 4057,
firstVisualChange: 4111,
firstPaint: 4115,
firstContentfulPaint: 4115,
firstMeaningfulPaint: 4115,
lastVisualChange: 17642,
firstCPUIdle: 7608,
firstInteractive: 7608,
load: 5043,
speedIndex: 6431,
totalBlockingTime: 200,
largestContentfulPaint: 4115,
cumulativeLayoutShift: 0
},
scoreOverview: {
firstContentfulPaint: {
score: 0.47,
value: 4114.5,
weight: 15
},
speedIndex: {
score: 0.4,
value: 6431,
weight: 15
},
largestContentfulPaint: {
score: 0.47,
value: 4114.5,
weight: 25
},
firstInteractive: {
score: 0.47,
value: 7607.5,
weight: 15
},
totalBlockingTime: {
score: 0.97,
value: 200,
weight: 25
},
cumulativeLayoutShift: {
score: 1,
value: 0,
weight: 5
}
},
requestTypes: {
Document: {
size: 106595,
encoded: 0,
count: 1
},
Font: {
size: 73360,
encoded: 0,
count: 4
},
Stylesheet: {
size: 316022,
encoded: 0,
count: 1
},
Image: {
size: 191384,
encoded: 0,
count: 7
},
Script: {
size: 1587992,
encoded: 0,
count: 12
},
XHR: {
size: 39994,
encoded: 0,
count: 2
},
Other: {
size: 6876,
encoded: 0,
count: 2
},
Media: {
size: 1360299,
encoded: 0,
count: 2
}
},
warnings: {}
},
type: 'hard'
}
]
Get All Screenshots
GET /rest/v1/{username}/jobs/{job_id}/assets/screenshots.zip
Retrieves all of the screenshot files for the specified job and downloads them as a single ZIP file. Use the --output <filepath>
cURL flag, as shown in the request samples, to download to a local directory.
Parameters
username | | PATH | REQUIRED | STRING | The username of the owner of the job. You can look up Sauce Labs users in your organization using the Lookup Users endpoint. |
job_id | | PATH | REQUIRED | STRING | The Sauce Labs identifier of the job for which you are retrieving the asset list. You can look up job IDs using the Get Jobs endpoint. |
- United States
- Europe
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-west-1.saucelabs.com/rest/v1/nancy.sweeney/jobs/bc3d1dbd96fd4479925f2afa8efbc090/assets/screenshots.zip' --output './screenshots.zip'
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.eu-central-1.saucelabs.com/rest/v1/nancy.sweeney/jobs/bc3d1dbd96fd4479925f2afa8efbc090/assets/screenshots.zip' --output './screenshots.zip'
Responses
200 | Success. Screenshots are downloaded to the specified output location. | |
401 | Not authorized. | |
404 | Not found. |
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 9 0 9 0 0 18 0 --:--:-- --:--:-- --:--:-- 18
Delete Job Assets
DELETE /rest/v1/{username}/jobs/{job_id}/assets
Sauce Labs retains job asset files for 30 days, after which, they are purged, but you can delete the asset files for a job before that, if desired. This request deletes all of the asset files associated with a job. Deleting a single asset file is not supported at this time.
Parameters
username | | PATH | REQUIRED | STRING | The username of the owner of the job. You can look up Sauce Labs users in your organization using the Lookup Users endpoint. |
job_id | | PATH | REQUIRED | STRING | The Sauce Labs identifier of the job for which you are retrieving the asset list. You can look up job IDs using the Get Jobs endpoint. |
- United States
- Europe
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request DELETE 'https://api.us-west-1.saucelabs.com/rest/v1/nancy.sweeney/jobs/bc3d1dbd96fd4479925f2afa8efbc090/assets' | json_pp
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request DELETE 'https://api.eu-central-1.saucelabs.com/rest/v1/nancy.sweeney/jobs/bc3d1dbd96fd4479925f2afa8efbc090/assets' | json_pp
Responses
200 | Success. | |
404 | Not found. |
;[
['0000screenshot.png', 11305],
['0001screenshot.png', 55109],
['0002screenshot.png', 55109],
['_crmuxdriver.log', 100136],
['_lhr_806270ED1EF8FA367C4CDC4083079F32.json.gz', 46316],
['_tracelog_806270ED1EF8FA367C4CDC4083079F32.json.gz', 1690435],
['automator.log', 281824],
['log.json', 6201],
['network.har', 14118],
['performance.json', 4812],
['selenium-server.log', 341436],
['video.mp4', 210140]
]
Builds Methods
DEPRECATED
Builds are now available to both RDC and VDC jobs. See the new Builds API for endpoints that incorporate this enhancement.
Get Builds
GET /rest/v1/{username}/builds
DEPRECATED
Get a list of recent builds run by the specified user.
Parameters
username | | PATH | REQUIRED | STRING | The username of the Sauce Labs users whose builds you are looking up. You can look up Sauce Labs users in your organization using the Lookup Users endpoint. |
- United States
- Europe
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.us-west-1.saucelabs.com/rest/v1/jsmith/builds' | json_pp
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request GET 'https://api.eu-central-1.saucelabs.com/rest/v1/jsmith/builds' | json_pp
Responses
200 | Success. | |
404 | Not found. |
[
{
"status": "failed",
"jobs": {
"completed": 0,
"finished": 44,
"queued": 0,
"failed": 22,
"running": 0,
"passed": 22,
"errored": 0,
"public": 0
},
"name": "Release",
"deletion_time": null,
"org_id": "******",
"start_time": 1618847969,
"creation_time": 1618847979,
"number": null,
"public": false,
"modification_time": 1618860999,
"prefix": null,
"end_time": 1618860985,
"passed": false,
"owner": "jsmith",
"run": 9,
"team_id": "******",
"group_id": "******",
"id": "45d7c21d1df748abbe9c425ab0ecbe4b"
},
{...}
]