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.

RDC Jobs

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 `json` or `csv`.

United States
Europe

Sample Request
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

Sample Request
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.

Sample Response
[
    {
        "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

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

Sample Request
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.

Sample Response
{
    "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.

RDC Jobs

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: `public` - Visibility is unrestricted and available to anyone on the internet. `public restricted` - Visibility is limited to the results page and video/screenshot assets. Logs and other metadata is hidden from unauthorized viewers. `share` - You can share your test using a dedicated link, but it is not listed publicly or indexed by search engines. `team` - Only members of the same team as the job owner can view the job. `private` - The owner of the job is the only person who is allowed to view it. Specify multiple roles as comma-separated values.
`passed`	\| BODY \| OPTIONAL \| BOOLEAN \| Asserts whether the job passed (`true`) or not (`false`).
`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

Sample Request
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"
    }
}'

Sample Request
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.

Sample Response
{
    "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

Sample Request
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

Sample Request
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.

Sample Response
{
    "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

Sample Request
curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
--request DELETE 'https://api.us-west-1.saucelabs.com/rest/v1.1/jobs/a521fd8a78c4426fb10ab765ab1f6831' | json_pp

Sample Request
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

Sample Request
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

Sample Request
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.

Sample Response
{
    "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

Sample Request
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

Sample Request
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.

Sample Response
;[
{
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

Sample Request
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'

Sample Request
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.

Sample Response
% 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

Sample Request
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

Sample Request
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.

Sample Response
;[
['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

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

Sample Request
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.

Sample Response
[
    {
        "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"
    },
    {...}
]

What You'll Need​

Jobs Methods​

Get Jobs​

Parameters​

Responses​

Get Job Details​

Parameters​

Responses​

Update a Job​

Parameters​

Responses​

Stop a Job​

Parameters​

Responses​

Delete a Job​

Parameters​

Responses​

List Job Assets​

Parameters​

Responses​

Get a Job Asset File​

Parameters​

Responses​

Get All Screenshots​

Parameters​

Responses​

Delete Job Assets​

Parameters​

Responses​

Builds Methods​

Get Builds​

Parameters​

Responses​

What You'll Need

Jobs Methods

Get Jobs

Parameters

Responses

Get Job Details

Parameters

Responses

Update a Job

Parameters

Responses

Stop a Job

Parameters

Responses

Delete a Job

Parameters

Responses

List Job Assets

Parameters

Responses

Get a Job Asset File

Parameters

Responses

Get All Screenshots

Parameters

Responses

Delete Job Assets

Parameters

Responses

Builds Methods

Get Builds

Parameters

Responses