jobs - Documentation

Source:

jobs/index.js, line 3

Methods

(static) artifactsDestroy(params, cb)

Source:

jobs/artifactsDestroy.js, line 7

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:

jobs/artifactsGet.js, line 11

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:

jobs/artifactsList.js, line 7

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:

jobs/clone.js, line 7

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:

jobs/create.js, line 19

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 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 true job will be sent to a preemptible VM only. Defaults to false.
`useDockerfile`	boolean	<optional>	Optional; if true the job will use the Dockerfile provided in the workspace to build a docker image and optionally run the resulting image as a container
`buildOnly`	boolean	<optional>	Optional; if this option is selected the job will build the Dockerfile and push to a selected remote registry only, without actually running the container. A registry target must be provided.
`registryTarget`	string	<optional>	Optional; a location to push docker images built from a Dockerfile. Must be included with a buildOnly flag. If useDockerfile is true and registryTarget is false the built container will be run but not pushed to a remote registry.
`registryTargetUsername`	string	<optional>	Optional; username credential for remote registry target
`registryTargetPassword`	string	<optional>	Optional; password credential for remote registry target
`relDockerfilePath`	string	<optional>	Optional; relative location of Dockefile in the workspace. Defaults to the top level "./Dockerfile" if not specified.

cb

function

Node-style error-first callback function

Returns:

job - The created job JSON object

Type: object

(static) destroy(params, cb)

Source:

jobs/destroy.js, line 7

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:

jobs/list.js, line 9

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

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 (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:

jobs/logs.js, line 7

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:

jobs/machineTypes.js, line 6

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

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:

jobs/show.js, line 7

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:

jobs/stop.js, line 7

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:

jobs/waitfor.js, line 7

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