jobs

jobs

Methods

(static) artifactsDestroy(params, cb)

Source:

Destroy artifact files of the job with the given id. The name of a particular file, or directory can be specified, and can include a wildcard character at the end, e.g., "myfiles*". If no specifc file or directory is specified all artifact files will be destroyed.

Examples
paperspace.jobs.artifactsDestroy({
  jobId: 'j123abc',
  files: 'myfiles*' // optional
}, function(err, res) {
  // handle error or result
});
$ paperspace jobs artifactsDestroy \
    --jobId "j123abc" \
    --files "myfiles*"
# HTTP request:
https://api.paperspace.io
POST /jobs/j123abc/artifactsDestroy?files=myfiles*
x-api-key: 1ba4f98e7c0...
# Returns 204 on success
Parameters:
Name Type Description
params object

Artifacts destroy parameters

Properties
Name Type Attributes Description
jobId string

The id of the job to destroy artifacts for

files string <optional>

Optional; if destroying only certain files, a wildcard pattern to match against, e.g., "myfiles*". Note: if you include a wildcard you must double-quote the files argument.

cb function

Node-style error-first callback function

(static) artifactsGet(params, cb)

Source:

Get the artifacts files for the job with the given id. The name of a particular file, or directory can be specified, and can include a wildcard character at the end, e.g., "myfiles"*. If no specifc file or directory is specified all artifact files will be retrieved.

Examples
paperspace.jobs.artifactsGet({
  jobId: 'j123abc'
}, function(err, res) {
  // handle error or result
});
$ paperspace jobs artifactsGet \
    --jobId "j123abc"
# HTTP request:
https://api.paperspace.io
GET /jobs/artifactsGet?jobId=j123abc&files=myfiles*
x-api-key: 1ba4f98e7c0...
# Returns 200 on success
//Example output:
Downloading myoutput1.txt
Downloading myoutput2.txt
Downloads finished
Parameters:
Name Type Description
params object

Artifacts get parameters

Properties
Name Type Attributes Description
jobId string

Id of the job to get artifacts for

files string <optional>

Optional; if getting only certain files, a wildcard pattern to match against, e.g., "myfiles*". Note: if you include a wildcard you must double-quote the files argument.

dest string <optional>

Optional; an existing directory to copy the artifacts files to.

json boolean <optional>

Optional; return JSON object instead of writing to standard out. '--json' with no value is equivalent to true.

cb function

Node-style error-first callback function

Returns:

one or more artifact files

(static) artifactsList()

Source:

List job artifact files for the specified job.

Examples
paperspace.jobs.artifactsList({
  jobId: 'j123abc',
  size: true
}, function(err, res) {
  // handle error or result
});
$ paperspace jobs artifactsList \
    --jobId "j123abc" \
    --size true
# HTTP request:
https://api.paperspace.io
GET /jobs/artifactsList?jobId=j123abc
x-api-key: 1ba4f98e7c0...
# Returns 200 on success
//Example return value:
[
  {
    "file": "myoutput1.txt"
    "size": 443141
  },
  {
    "file": "myoutput2.txt"
    "size": 1456
  }
]
Parameters:
Name Type Attributes Description
params.jobId string

Id of the job to list artifacts for

params.files string <optional>

Optional; wildcard expression of file(s) to list, e.g., "myfiles*". Note: if you include a wildcard you must double-quote the files argument.

params.size boolean <optional>

Optional; include file size in bytes. '--size' with no value is equivalent to true.

params.links boolean <optional>

Optional; include https links to artifacts. Note: links are only valid for 8 hours. '--links' with no value is equivalent to true.

params.json boolean <optional>

Optional; return JSON object instead of writing to standard out. '--json' with no value is equivalent to true.

Returns:

artifact files list

(static) clone(params, cb)

Source:

Clone an exiting job and queue the cloned copy to run.

Examples
paperspace.jobs.clone({
  jobId: 'j123abc',
}, function(err, res) {
  // handle error or result
});
$ paperspace jobs clone --jobId "j123abc"
# HTTP request:
https://api.paperspace.io
POST /jobs/j123abc/clone
x-api-key: 1ba4f98e7c0...
# Returns 200 on success
//Example return value:
{
  "id": "j345abc",
  "name": "job for project myproject",
  "state": "Pending",
  "workspaceUrl": "myproject.zip",
  "workingDirectory": "/paperspace",
  "artifactsDirectory": "/artifacts",
  "entrypoint": "echo Hello Paperspace",
  "projectId": "pr456def",
  "project": "myproject",
  "container": "http://dockerhub.com/mycontainer",
  "machineType": "P5000",
  "cluster": "PS Jobs",
  "usageRate": "P5000 hourly",
  "startedByUserId": "u789ghi",
  "parentJobId": "j123abc",
  "jobError": null,
  "dtCreated": "2017-11-30T19:20:38.956Z",
  "dtModified": "2017-11-30T19:20:39.744Z",
  "dtProvisioningStarted": null,
  "dtProvisioningFinished": null,
  "dtStarted": null,
  "dtFinished": null,
  "dtTeardownStarted": null,
  "dtTeardownFinished": null,
  "dtDeleted": null,
  "exitCode": null
}
Parameters:
Name Type Description
params object

Job clone parameters

Properties
Name Type Description
jobId string

Id of the job to clone

cb function

Node-style error-first callback function

(static) create(params, cb) → {object}

Source:

Create a new Paperspace job, and tail its log output if run at the command line. To disable the tailing behavior specify '--tail false'. Note: if a project is not defined for the current working directory, and you are running in command line mode, a project configuration settings file will be created. Use '--init false' or specify '--project [projectname]' to override this behavior.

Examples
paperspace.jobs.create({
  container: 'http://dockerhub.com/mycontainer',
  machineType: 'P5000',
}, function(err, res) {
  // handle error or result
});
$ paperspace jobs create \
    --container "http://dockerhub.com/mycontainer" \
    --machineType "P5000"
# HTTP request:
https://api.paperspace.io
POST /jobs/createJob { "container": "http://dockerhub.com/mycontainer", "machineType": "P5000" }
x-api-key: 1ba4f98e7c0...
# Returns 201 on success
// Example return value:
{
  "id": "j123abc",
  "name": "job for project myproject",
  "state": "Pending",
  "workspaceUrl": "myproject.zip",
  "workingDirectory": "/paperspace",
  "artifactsDirectory": "/artifacts",
  "entrypoint": "echo Hello Paperspace",
  "projectId": "pr456def",
  "project": "myproject",
  "container": "http://dockerhub.com/mycontainer",
  "machineType": "P5000",
  "cluster": "PS Jobs",
  "usageRate": "P5000 hourly",
  "startedByUserId": "u789ghi",
  "parentJobId": null,
  "jobError": null,
  "dtCreated": "2017-11-30T18:46:10.394Z",
  "dtModified": "2017-11-30T18:46:10.394Z",
  "dtProvisioningStarted": null,
  "dtProvisioningFinished": null,
  "dtStarted": null,
  "dtFinished": null,
  "dtTeardownStarted": null,
  "dtTeardownFinished": null,
  "dtDeleted": null,
  "exitCode": null
  "storageRegion": "East Coast (NY2)",
  "clusterMachine": "psABCD123",
  "ipAddress": "10.100.0.10",
  "ports": "6006:6006",
}
Parameters:
Name Type Description
params object

Job creation parameters

Properties
Name Type Attributes Description
container string

A required reference to a docker image in a public or private docker registry, or a container name provided by Paperspace. Docker image repository references must be in lowercase and may include a tag and a hostname prefix followed by a slash; if ommitted the hostname defaults to that of the public Docker Hub registry. An example docker image reference: 'docker.io/mynamespace/myimage:mytag'. A container name may be mixed case. (Designated container names are currently only provided as part of various Gradient tutorials and samples.)

cluster string <optional>

An optional cluster name of a cluster to run the job on. Only one of cluster or clusterId may be specified.

clusterId string <optional>

An optional cluster id of a cluster to run the job on. Only one of cluster or clusterId may be specified.

machineType string <optional>

An optional machine type to run the job on: either 'GPU+', 'P4000', 'P5000', 'P6000', 'V100', 'K80', 'P100', 'TPU', or 'GradientNode'.

Defaults to 'K80'.

Note: the 'K80', 'P100', and 'TPU' machineTypes run on Google Cloud Platform (GCP). The other machineTypes run on the Paperspace Cloud. Google Cloud platform and Paperspace Cloud have distict Job Storage spaces; Job storage is not currently shared between these two cloud environments.

name string <optional>

An optional name or description for this job. If ommitted, the job name defaults to 'job N' where N represents the Nth job instance for the given project.

project string <optional>

The name of the project for this job. If not provided, this is taken from the .ps_project/config.json file, or the current directory name.

projectId string <optional>

The poject id of an existing project for this job. Note: if projectId is specified, the project parameter cannot be specified.

command string <optional>

An optional command to run within the workspace or container.

workspace string <optional>

An optional path to a workspace, or link to a git repository to upload and merge with the container. If a zip file name is provided it is uploaded instead. If no workspace is provided the current directory is zipped up and transferred. If the workspace is 'none', no workspace is merged and the container is run as-is. To download a git repository provide an https repository link and optionally prefix it with 'git+', e.g. 'https://github.com/MyProjects/MyRepo.git'. If the 'git+' prefix is not specified, it is added at the time of download to the job runner machine. S3 links are also supported using the schema 's3://bucketname/objectname'.

ignoreFiles string <optional>

An optional reference to files or folders that should be excluded from workspace upload. Files/folders to be ignored, comma seperated if multiple.

codeCommit string <optional>

An optional reference to git commit hash if local workspace is a git repository. Found at runtime.

dataset string <optional>

An optional reference to a dataset to be merged with the container.

registryUsername string <optional>

An optional username for accessing an image hosted on a private container registry. Note: you must specify this option every time a private image is specified for the container.

registryPassword string <optional>

An optional password for accessing an image hosted on a private container registry. Note: you must specify this option every time a private image is specified for the container.

workspaceUsername string <optional>

An optional username for accessing a private git repository. Note: you must specify this option every time a private git repository is specified for the workspace.

workspacePassword string <optional>

An optional password for accessing a private git repository. We recommned using an OAuth token (GitHub instructions can be found here). Note: you must specify this option every time a private git repository is specified for the workspace.

ports string <optional>

An optional list of port mappings to open on the job cluster machine while the job is running. The port mappings are specified as 'XXXX:YYYY' where XXXX is an external port number and YYYY is an internal port number. Mulitple port mappings can be provided as a comma separated list. Port numbers must be greater than 1023. Note: only /tcp protocol usage is supported.

sharedMemMBytes number <optional>

Optional; shared memory size for the job container in megabytes (1 megabyte = 1024 * 1024 bytes). Cannot exceed total memory size for the given machine type.

nodeAttrs number <optional>

Optional; a JSON expression describing the node attributes for a compatible GradientNode machine to run this job. See the Gradient-Node documentation for more info.

tail boolean <optional>

Optional; defaults to true in command line mode only. Specify false to disable automatic tailing.

json boolean <optional>

Optional; if true, do not write progress to standard out. '--json' with no value is equivalent to true.

isPreemptible boolean <optional>

Optional; if included job will be sent to a preemptible VM only. Defaults to false.

cb function

Node-style error-first callback function

Returns:

job - The created job JSON object

Type
object

(static) destroy(params, cb)

Source:

Destroy the job with the given id. When this action is performed, the job is immediately stopped and marked for deletion. Access to the job is terminated immediately and billing for the job is prorated to the minute.

Examples
paperspace.jobs.destroy({
  jobId: 'j123abc',
}, function(err, res) {
  // handle error or result
});
$ paperspace jobs destroy --jobId "j123abc"
# HTTP request:
https://api.paperspace.io
POST /jobs/j123abc/destroy
x-api-key: 1ba4f98e7c0...
# Returns 204 on success
Parameters:
Name Type Description
params object

Job destroy parameters

Properties
Name Type Description
jobId string

The id of the job to destroy

cb function

Node-style error-first callback function

(static) list(filteropt, summaryopt, cb) → {array}

Source:

List information about all jobs available to either the current authenticated user or the team, if the user belongs to a team. The list method takes an optional first argument to limit the returned job objects.

Examples
paperspace.jobs.list(
  project: 'MyProject'
}, function(err, res) {
  // handle error or result
});
$ paperspace jobs list --project "MyProject" --state Running --summary
# HTTP request:
https://api.paperspace.io
GET /jobs/getJobs?project=MyProject
x-api-key: 1ba4f98e7c0...
# Returns 200 on success
//Example return value:
[
  {
    "id": "j123abc",
    "name": "My Job",
    "state": "running"
    "id": "j123abc",
    "name": "job for project myproject",
    "state": "Stopped",
    "workspaceUrl": "myproject.zip",
    "workingDirectory": "/paperspace",
    "artifactsDirectory": "/artifacts",
    "entrypoint": "echo Hello Paperspace",
    "projectId": "pr456def",
    "project": "myproject",
    "container": "http://dockerhub.com/mycontainer",
    "machineType": "P5000",
    "cluster": "PS Jobs",
    "usageRate": "P5000 hourly",
    "startedByUserId": "u789ghi",
    "parentJobId": null,
    "jobError": null,
    "dtCreated": "2017-11-30T18:46:10.394Z",
    "dtModified": "2017-11-30T18:46:10.394Z",
    "dtProvisioningStarted": "2017-11-30T18:46:50.467Z",
    "dtProvisioningFinished": "2017-11-30T18:47:12.508Z",
    "dtStarted": "2017-11-30T18:47:14.636Z",
    "dtFinished": "2017-11-30T18:52:44.209Z",
    "dtTeardownStarted": "2017-11-30T18:52:56.889Z",
    "dtTeardownFinished": "2017-11-30T18:53:31.734Z",
    "dtDeleted": null,
    "exitCode": 0
  }
]
Parameters:
Name Type Attributes Description
filter object <optional>

An optional filter object to limit the returned job objects

Properties
Name Type Attributes Description
project string <optional>

Optional project to match on. If neither project nor projectId are provided, this is taken from the .ps_project/config.json file, or the current directory name. Specify 'all' to list jobs for all projects associated with the user or team if the user is on a team.

projectId string <optional>

Optional projectId to match on

name string <optional>

Optional job name to match on

machineType string <optional>

Optional machineType to match on

state string <optional>

Optional state value to match on

container string <optional>

Optional container to match on

command string <optional>

Optional command to match on

workspace string <optional>

Optional workspace path to match on. Note: the original workspace path will be modified on upload to point to a temporary location.

dataset string <optional>

Optional dataset to match on

dataset string <optional>

Optional dataset to match on

summary boolean <optional>

Optional (command line argument only). Format output as a summary table.

cb function

Node-style error-first callback function

Returns:

[ job, ... ] - JSON array of job objects

Type
array

(static) logs(params, cb)

Source:

Stream the logs for the job with the given id, while the job is running or after it has stopped.

Examples
paperspace.jobs.logs({
  jobId: 'j123abc',
}, function(err, res) {
  // handle error or result
});
$ paperspace jobs logs \
    --jobId "j123abc"
# HTTP request:
https://logs.paperspace.io
GET /jobs/logs?jobId=j123abc
x-api-key: 1ba4f98e7c0...
# Returns 200 on success
//Example output:
Hello Paperspace
Creating file /artifacts/myoutput1.txt
Creating file /artifacts/myoutput2.txt
Finished; returning exit code 0
Parameters:
Name Type Description
params object

Job logs parameters

Properties
Name Type Attributes Description
jobId string

Id of the job to logs

tail boolean <optional>

Optional; if tail is specified logs will be streamed until the job stops.

line number <optional>

Optional; if line is specified logs only logs after that line will be returned (up to limit).

limit number <optional>

Optional; number of log lines to retrieve on each request; default limit is 2000.

json boolean <optional>

Optional; return JSON object instead of writing to standard out. '--json' with no value is equivalent to true.

cb function

Node-style error-first callback function

Returns:

logs - The job logs

(static) machineTypes(filteropt, cb) → {array}

Source:

Return a list of available cluster machine types. If the isBusy property is true then all machines of the specified type and cluster are currently running jobs. The machineTypes method takes an optional first argument to limit the returned cluster machine type objects.

Examples
paperspace.jobs.machineTypes({
  // region: 'East Coast (NY2)', // optional filter on region
  // cluster: 'PS Jobs', // optional filter on cluster
  // machineType: 'P5000', // optional filter on machine type 	
  // isBusy: false, // optional filter on busy status 	
}, function(err, res) {
  // handle error or result
});
$ paperspace jobs machineTypes
# HTTP request:
https://api.paperspace.io
GET /jobs/getClusterAvailableMachineTypes
x-api-key: 1ba4f98e7c0...
# Returns 200 on success
//Example return value:
[
  {
    "region": "East Coast (NY2)",
    "cluster": "PS Jobs",
    "machineType": "P5000",
    "isBusy": false,
  },
  {
    "region": "East Coast (NY2)",
    "cluster": "PS Jobs",
    "machineType": "V100",
    "isBusy": false,
  },
  {
    "region": "GCP West",
    "cluster": "PS Jobs on GCP",
    "machineType": "K80",
    "isBusy": false,
  },
  {
    "region": "GCP West",
    "cluster": "PS Jobs on GCP",
    "machineType": "P100",
    "isBusy": false,
  }
]
Parameters:
Name Type Attributes Description
filter object <optional>

An optional filter object to limit the returned job objects

Properties
Name Type Attributes Description
region string <optional>

Optional region to match on

cluster string <optional>

Optional cluster to match on

machineType string <optional>

Optional machine type to macth on

isBusy boolean <optional>

Optional busy status value to match on

cb function

Node-style error-first callback function

Returns:

[ clusterMachineType, ... ] - JSON array of available cluster machine type objects

Type
array

(static) show(params, cb) → {object}

Source:

Show job information for the job with the given id.

Examples
paperspace.jobs.show({
  jobId: 'j123abc',
}, function(err, res) {
  // handle error or result
});
$ paperspace jobs show \
    --jobId "j123abc"
# HTTP request:
https://api.paperspace.io
GET /jobs/getJob?jobId=j123abc
x-api-key: 1ba4f98e7c0...
# Returns 200 on success
//Example return value:
{
  "id": "j123abc",
  "name": "job for project myproject",
  "state": "Running",
  "workspaceUrl": "myproject.zip",
  "workingDirectory": "/paperspace",
  "artifactsDirectory": "/artifacts",
  "entrypoint": "echo Hello Paperspace",
  "projectId": "pr456def",
  "project": "myproject",
  "container": "http://dockerhub.com/mycontainer",
  "machineType": "P5000",
  "cluster": "PS Jobs",
  "usageRate": "P5000 hourly",
  "startedByUserId": "u789ghi",
  "parentJobId": null,
  "jobError": null,
  "dtCreated": "2017-11-30T18:46:10.394Z",
  "dtModified": "2017-11-30T18:46:10.394Z",
  "dtProvisioningStarted": "2017-11-30T18:46:50.467Z",
  "dtProvisioningFinished": "2017-11-30T18:47:12.508Z",
  "dtStarted": "2017-11-30T18:47:14.636Z",
  "dtFinished": null,
  "dtTeardownStarted": null,
  "dtTeardownFinished": null,
  "dtDeleted": null,
  "exitCode": null
}
Parameters:
Name Type Description
params object

Job show parameters

Properties
Name Type Description
jobId string

Id of the job to show

cb function

Node-style error-first callback function

Returns:

job - The job JSON object

Type
object

(static) stop(params, cb)

Source:

Stop an individual job. If the job is already stopped, this action is a no-op. If the job is running, it will be stopped.

Examples
paperspace.jobs.stop({
  jobId: 'j123abc',
}, function(err, res) {
  // handle error or result
});
$ paperspace jobs stop --jobId "j123abc"
# HTTP request:
https://api.paperspace.io
POST /jobs/j123abc/stop
x-api-key: 1ba4f98e7c0...
# Returns 204 on success
Parameters:
Name Type Description
params object

Job stop parameters

Properties
Name Type Description
jobId string

Id of the job to shut down

cb function

Node-style error-first callback function

(static) waitfor(params, cb) → {object}

Source:

Wait for the job with the given id to enter a certain job state. This action polls the server and returns only when we detect that the job has transitioned into the given state, or to the 'Error' state. States available to query for are:

  • Pending - the job has not started setting up on a machine yet
  • Running - the job is setting up on a machine, running, or tearing down
  • Stopped - the job finished with a job command exit code of 0
  • Error - the job was unable to setup or run to normal completion
  • Failed - the job finished but the job command exit code was non-zero
  • Cancelled - the job was manual stopped before completion

When the callback is called, the returned object will be information about the job.

Examples
paperspace.job.waitfor({
  jobId: 'j123abc',
  state: 'Stopped',
}, function(err, res) {
  // handle error or result
});
$ paperspace jobs waitfor \
    --jobId "j123abc" \
    --state "Stopped"
# HTTP request:
# The waitefor method is only available using the API client.
# Use the jobs show method to query the state of the job via HTTP.
//Example return value:
{
  "id": "j123abc",
  "name": "job for project myproject",
  "state": "Stopped",
  "workspaceUrl": "myproject.zip",
  "workingDirectory": "/paperspace",
  "artifactsDirectory": "/artifacts",
  "entrypoint": "echo Hello Paperspace",
  "projectId": "pr456def",
  "project": "myproject",
  "container": "http://dockerhub.com/mycontainer",
  "machineType": "P5000",
  "cluster": "PS Jobs",
  "usageRate": "P5000 hourly",
  "startedByUserId": "u789ghi",
  "parentJobId": null,
  "jobError": null,
  "dtCreated": "2017-11-30T18:46:10.394Z",
  "dtModified": "2017-11-30T18:46:10.394Z",
  "dtProvisioningStarted": "2017-11-30T18:46:50.467Z",
  "dtProvisioningFinished": "2017-11-30T18:47:12.508Z",
  "dtStarted": "2017-11-30T18:47:14.636Z",
  "dtFinished": "2017-11-30T18:52:44.209Z",
  "dtTeardownStarted": "2017-11-30T18:52:56.889Z",
  "dtTeardownFinished": "2017-11-30T18:53:31.734Z",
  "dtDeleted": null,
  "exitCode": 0
}
Parameters:
Name Type Description
params object

Job waitfor parameters

Properties
Name Type Description
jobId string

Id of the job to wait for

state string

Name of the state to wait for

cb function

Node-style error-first callback function

Returns:

job - The job JSON object

Type
object