Sauce Labs Jobs API
The Jobs API from Sauce Labs — 3 operation(s) for jobs.
OpenAPI Specification
openapi: 3.0.3
info:
title: Sauce Labs Devices Jobs API
description: Manage and retrieve test jobs running on Sauce Labs virtual and real device infrastructure. Supports listing jobs, fetching job assets such as logs, videos, and screenshots, updating job attributes, and stopping or deleting jobs.
version: '1.1'
contact:
name: Sauce Labs Support
url: https://support.saucelabs.com
termsOfService: https://saucelabs.com/terms-of-service
license:
name: Proprietary
url: https://saucelabs.com/terms-of-service
servers:
- url: https://api.us-west-1.saucelabs.com
description: US West (primary)
- url: https://api.eu-central-1.saucelabs.com
description: EU Central
security:
- basicAuth: []
tags:
- name: Jobs
paths:
/v1/{username}/jobs:
get:
operationId: listJobs
summary: List Jobs for a User
description: Returns a list of test jobs for the specified user.
tags:
- Jobs
parameters:
- name: username
in: path
required: true
schema:
type: string
description: The Sauce Labs username.
- name: limit
in: query
schema:
type: integer
default: 20
maximum: 500
description: Maximum number of jobs to return.
- name: skip
in: query
schema:
type: integer
default: 0
description: Number of jobs to skip (for pagination).
- name: from
in: query
schema:
type: integer
description: Unix timestamp; return jobs created after this time.
- name: to
in: query
schema:
type: integer
description: Unix timestamp; return jobs created before this time.
- name: status
in: query
schema:
type: string
enum:
- new
- queued
- in progress
- passed
- failed
- error
- complete
description: Filter by job status.
responses:
'200':
description: A list of job summaries.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/JobSummary'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/{username}/jobs/{id}:
get:
operationId: getJob
summary: Get a Job
description: Returns full details for a specific job by ID.
tags:
- Jobs
parameters:
- name: username
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
description: The job ID.
responses:
'200':
description: Job details.
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: updateJob
summary: Update a Job
description: Update attributes of an existing job such as name, tags, or pass/fail status.
tags:
- Jobs
parameters:
- name: username
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/JobUpdate'
responses:
'200':
description: Updated job details.
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteJob
summary: Delete a Job
description: Permanently deletes a job and all associated assets.
tags:
- Jobs
parameters:
- name: username
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Job successfully deleted.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v1/{username}/jobs/{id}/stop:
put:
operationId: stopJob
summary: Stop a Running Job
description: Terminates a running or queued job immediately.
tags:
- Jobs
parameters:
- name: username
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Job stopped successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
'401':
$ref: '#/components/responses/Unauthorized'
components:
schemas:
JobSummary:
type: object
description: Abbreviated job information for list responses.
properties:
id:
type: string
status:
type: string
enum:
- new
- queued
- in progress
- passed
- failed
- error
- complete
passed:
type: boolean
nullable: true
name:
type: string
build:
type: string
nullable: true
creation_time:
type: integer
start_time:
type: integer
nullable: true
end_time:
type: integer
nullable: true
Job:
type: object
description: Full details of a Sauce Labs test job.
properties:
id:
type: string
description: Unique job identifier.
name:
type: string
description: Human-readable job name.
status:
type: string
enum:
- new
- queued
- in progress
- passed
- failed
- error
- complete
description: Current status of the job.
passed:
type: boolean
nullable: true
description: Whether the job was marked as passed.
owner:
type: string
description: Username of the job owner.
build:
type: string
nullable: true
description: Build identifier associated with this job.
browser:
type: string
description: Browser used in the job.
browser_version:
type: string
description: Browser version used.
browser_short_version:
type: string
description: Short browser version string.
os:
type: string
description: Operating system used.
automation_backend:
type: string
description: Automation framework (e.g., webdriver, appium).
creation_time:
type: integer
description: Unix timestamp when the job was created.
start_time:
type: integer
nullable: true
description: Unix timestamp when the job started running.
end_time:
type: integer
nullable: true
description: Unix timestamp when the job ended.
modification_time:
type: integer
description: Unix timestamp of last modification.
tags:
type: array
items:
type: string
description: User-defined tags for categorizing jobs.
public:
type: string
description: Visibility setting (public, private, team, share).
video_url:
type: string
format: uri
nullable: true
description: URL to the recorded video of the session.
log_url:
type: string
format: uri
nullable: true
description: URL to the Selenium log.
commands_not_successful:
type: integer
description: Count of commands that did not succeed.
consolidated_status:
type: string
description: Consolidated pass/fail status string.
assigned_tunnel_id:
type: string
nullable: true
description: Sauce Connect tunnel ID used by this job.
proxied:
type: boolean
description: Whether the job was proxied through Sauce Connect.
record_screenshots:
type: boolean
description: Whether screenshots were recorded.
record_video:
type: boolean
description: Whether video was recorded.
selenium_version:
type: string
nullable: true
description: Selenium version used.
JobUpdate:
type: object
description: Fields that can be updated on an existing job.
properties:
name:
type: string
description: New display name for the job.
passed:
type: boolean
description: Set pass/fail status for the job.
tags:
type: array
items:
type: string
description: Replace the list of tags.
build:
type: string
description: Set or update the build name.
public:
type: string
enum:
- public
- private
- team
- share
description: Update the visibility of the job.
custom-data:
type: object
additionalProperties: true
description: Arbitrary key-value metadata.
Error:
type: object
description: Error response envelope.
properties:
errors:
type: array
items:
type: string
description: List of error messages.
message:
type: string
description: Summary error message.
responses:
NotFound:
description: The requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Authentication credentials are missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
basicAuth:
type: http
scheme: basic
description: Use your Sauce Labs username and access key as the HTTP Basic Authentication credentials.
externalDocs:
description: Sauce Labs Jobs API Documentation
url: https://docs.saucelabs.com/dev/api/jobs/