machines

machines

Source:

Methods

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

Source:

Get machine availability for the given region and machine type. Note: availability is only provided for the dedicated GPU machine types. Also, not all machine types are available in all regions.

Examples
paperspace.machines.availability({
  region: 'East Coast (NY2)',
  machineType: 'GPU+',
}, function(err, res) {
  // handle error or result
});
$ paperspace machines availability \
    --region "East Coast (NY2)" \
    --machineType "GPU+"
# HTTP request:
https://api.paperspace.io
GET /machines/getAvailability?region=East%20Coast%20(NY2)&machineType=GPU%2B
x-api-key: 1ba4f98e7c0...
# Returns 200 on success
//Example return value:
{
  "available": true
}
Parameters:
Name Type Description
params object

Machine utilization parameters

Properties
Name Type Description
region string

Name of the region: either 'East Coast (NY2)', 'West Coast (CA1)', or 'Europe (AMS1)'
machineType string

Machine type: either 'GPU+', 'P4000', 'P5000', 'P6000', or 'V100'
cb function

Node-style error-first callback function
Returns:

availability - The availability JSON object, containing a single boolean attribute, "available". A value of true for "available" means machines of that type can currently be requested in that region. A value of false means that requests for that machine type are not currently available in that region.

Type
object

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

Source:

Create a new Paperspace virtual machine. If you are using an individual account, you will be assigned as the owner of the machine. If you are a team administrator, you must specify the user that should be assigned to the machine, either by specifing a user id, or by providing an email address, password, first name and last name for the creation of a new user on the team. (The email address must not already be associated with a Paperspace account, otherwise a user creation error is returned.)

Note: if you attempt to create a new user along with the machine, the user creation step is executed before the creation of the machine. Therefore, if an error occurs, the user creation step may or may not have succeeded. To deal with this, if an error object is returned from the machines create method, subsquently call the users list method (with a search filter specifying the email address) to check if the user creation step succeeded.

Note: machine creation is not always guaranteed to succeed, due to various possible issues such as machine availability, billing issues, resource issues, or system errors. However you can call the machines availability method to check for current point-in-time availability of a given machine type.

This machine create action can only be performed by the account owner. (Team members cannot create machines themselves; only the team administrator may do so.)

Examples
paperspace.machines.create({
  region: 'East Coast (NY2)',
  machineType: 'Air',
  size: 50,
  billingType: 'hourly',
  machineName: 'My Machine 1',
  templateId: 't123abc',
  assignPublicIp: true, // optional - assign a new public ip address
  networkId: 'n123abc', // optional - only if creating on a specific network
  teamId: 'te456def', // optional - required if creating this machine for a team
  email: 'example@example.com', // optional - if creating a new user
  password: 'secret123', // optional - if creating a new user
  firstName: 'Jon', // optional - if creating a new user
  lastName: 'Snow', // optional - if creating a new user
  notificationEmail: 'example@example.com', // optional - address to send a notification when complete
  scriptId: 'sc123abc', // optional - a script to be run on startup
}, function(err, res) {
  // handle error or result
});
$ paperspace machines create \
    --region "East Coast (NY2)" \
    --machineType "Air" \
    --size 50 \
    --billingType "hourly" \
    --machineName "My Machine 1" \
    --templateId "t123abc" \
    --assignPublicIp true \
    --networkId "n123abc" \
    --teamId "te456def" \
    --userId "u123abc" \
    --email "example@example.com" \
    --password "secret123" \
    --firstName "Jon" \
    --lastName "Snow" \
    --notificationEmail "example@example.com" \
    --scriptId "sc123abc"
# HTTP request:
https://api.paperspace.io
POST /machines/createSingleMachinePublic {"region": "East Coast (NY2)", "machineType": "Air", "size": 50, "billingType": "monthly", "machineName": "My Machine 1", "templateId": "t123abc", "assignPublicIp": true, "networkId": "n123abc", "teamId": "te456def", "email": "example@example.com", "password": "secret123", "firstName": "Jon", "lastName": "Snow", "notificationEmail": "example@example.com"}
x-api-key: 1ba4f98e7c0...
# Returns 201 on success
// Example return value:
{
  "id": "ps123abc",
  "name": "My Machine",
  "os": null,
  "ram": null,
  "cpus": 1,
  "gpu": null,
  "storageTotal": null,
  "storageUsed": null,
  "usageRate": "Air hourly",
  "shutdownTimeoutInHours": 24,
  "shutdownTimeoutForces": false,
  "performAutoSnapshot": false,
  "autoSnapshotFrequency": null,
  "autoSnapshotSaveCount": null,
  "agentType": "WindowsDesktop",
  "dtCreated": "2017-02-16T20:26:54.880Z",
  "state": "provisioning",
  "updatesPending": false,
  "networkId": null,
  "privateIpAddress": null,
  "publicIpAddress": "169.255.255.254",
  "region": null,
  "userId": "u123abc",
  "teamId": "te456def",
  "scriptId": "sc123abc",
  "dtLastRun": null,
  "dynamicPublicIp": null
}
Parameters:
Name Type Description
params object

Machine creation parameters

Properties
Name Type Attributes Description
region string

Name of the region: either 'East Coast (NY2)', 'West Coast (CA1)', or 'Europe (AMS1)'
machineType string

Machine type: either 'Air', 'Standard', 'Pro', 'Advanced', 'GPU+', 'P4000', 'P5000', 'P6000', 'V100', 'C1', 'C2', 'C3', 'C4', 'C5', 'C6', 'C7', 'C8', 'C9', or 'C10'

Note:
Windows os templates cannot be used to create CPU-only machine types 'C1' - 'C10'.
Ubuntu os templates cannot be used to create GRID GPU machine types: 'Air', 'Standard', 'Pro', or 'Advanced'.
size number

Storage size for the machine in GB
billingType string

Either 'monthly' or 'hourly' billing
machineName string

A memorable name for this machine
templateId string

Template id of the template to use for creating this machine
assignPublicIp boolean <optional>

Assign a new public ip address on machine creation. Cannot be used with dynamicPublicIp.
dynamicPublicIp boolean <optional>

Assigns a new public ip address on machine start and releases it from the account on machine stop. Cannot be used with assignPublicIp.
networkId string <optional>

If creating on a specific network, specify its id
teamId string <optional>

If creating the machine for a team, specify the team id
userId string <optional>

If assigning to an existing user other than yourself, specify the user id (mutually exclusive with email, password, firstName, lastName)
email string <optional>

If creating a new user for this machine, specify their email address (mutually exclusive with userId)
password string <optional>

If creating a new user, specify their password (mutually exclusive with userId)
firstName string <optional>

If creating a new user, specify their first name (mutually exclusive with userId)
lastName string <optional>

If creating a new user, specify their last name (mutually exclusive with userId)
notificationEmail string <optional>

Send a notification to this email address when complete
scriptId string <optional>

The script id of a script to be run on startup. See the Script Guide for more info on using scripts.
cb function

Node-style error-first callback function
Returns:

machine - The created machine JSON object

Type
object

(static) destroy(params, cb)

Source:

Destroy the machine with the given id. When this action is performed, the machine is immediately shut down and marked for deletion from the datacenter. Any snapshots that were derived from the machine are also deleted. Access to the machine is terminated immediately and billing for the machine is prorated to the hour. This action can only be performed by the user who owns the machine, or in the case of a team, the team administrator.

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

Machine destroy parameters

Properties
Name Type Attributes Description
machineId string

The id of the machine to destroy
releasePublicIp boolean <optional>

releases any assigned public ip address for the machine; defaults to false
cb function

Node-style error-first callback function

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

Source:

List information about all machines 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 machine objects.

Examples
paperspace.machines.list(function(err, res) {
  // handle error or result
});
$ paperspace machines list
# HTTP request:
https://api.paperspace.io
GET /machines/getMachines
x-api-key: 1ba4f98e7c0...
# Returns 200 on success
//Example return value:
[
  {
    "id": "ps123abc",
    "name": "My Machine",
    "os": "Microsoft Windows Server 2016 Datacenter",
    "ram": "8589938688",
    "cpus": 4,
    "gpu": "GRID K160Q (2GB)",
    "storageTotal": "53687091200",
    "storageUsed": "110080",
    "usageRate": "Air monthly",
    "shutdownTimeoutInHours": 168,
    "shutdownTimeoutForces": false,
    "performAutoSnapshot": false,
    "autoSnapshotFrequency": null,
    "autoSnapshotSaveCount": null,
    "agentType": "WindowsDesktop",
    "dtCreated": "2016-11-18T05:18:29.533Z",
    "state": "ready",
    "updatesPending": false,
    "networkId": "n789ghi",
    "privateIpAddress": "10.64.21.47",
    "publicIpAddress": null,
    "region": "East Coast (NY2)",
    "userId": "u123abc",
    "teamId": "te456def",
    "scriptId": "sc123abc",
    "dtLastRun": "2017-06-30T07:22:49.763Z",
    "dynamicPublicIp": null
  }
]
Parameters:
Name Type Attributes Description
filter object <optional>

An optional filter object to limit the returned machine objects

Properties
Name Type Attributes Description
machineId string <optional>

Optional machine id to match on. Note: must be specified as "machineId", not "id".
name string <optional>

Optional name to match on
os string <optional>

Optional os to match on
ram string <optional>

Optional ram value to match on
cpus number <optional>

Optional cpu count to match on
gpu string <optional>

Optional gpu to match on
storageTotal string <optional>

Optional storageTotal value to match on
storageUsed string <optional>

Optional storageUsed value to match on
usageRate string <optional>

Optional usageRate value to match on
shutdownTimeoutInHours number <optional>

Optional shutdownTimeoutInHours value to match on
performAutoSnapshot boolean <optional>

Optional performAutoSnapshot value to match on, either true or false
autoSnapshotFrequency string <optional>

Optional autoSnapshotFrequency value to match on
autoSnapshotSaveCount number <optional>

Optional autoSnapshotSaveCount value to match on
agentType string <optional>

Optional agentType value to match on
dtCreated string <optional>

Optional datetime created value to match on
state string <optional>

Optional state value to match on
updatesPending boolean <optional>

Optional updatesPending value to match on
networkId string <optional>

Optional networkId to match on
privateIpAddress string <optional>

Optional privateIpAddress to match on
publicIpAddress string <optional>

Optional publicIpAddress to match on
region string <optional>

Optional region to match on
userId string <optional>

Optional userId to match on
teamId string <optional>

Optional teamId to match on
scriptId string <optional>

Optional scriptId to match on
dtLastRun string <optional>

Optional script datetime last run value to match on
cb function

Node-style error-first callback function
Returns:

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

Type
array

(static) restart(params, cb)

Source:

Restart an individual machine. If the machine is already restarting, this action will request the machine be restarted again. This action can only be performed by the user who owns the machine.

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

Machine restart parameters

Properties
Name Type Description
machineId string

Id of the machine to restart
cb function

Node-style error-first callback function

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

Source:

Show machine information for the machine with the given id.

The state property can take on the follow values:

  • off
  • starting - machine is in the process of changing to the ready or serviceready state
  • stopping - machine is in the process of changing to the off state
  • restarting - combines stopping follow immediately by starting
  • serviceready - services are running on the machine but the Paperspace agent is not yet available
  • ready - services are running on machine and the Paperspace agent is ready to stream or accept logins
  • upgrading - the machine specification are being upgraded, which involves a shutdown and startup sequence
  • provisioning - the machine is in the process of being created for the first time

The updatesPending property is either true or false and reflects whether the operating system has scheduled updates for the next machine state transition, e.g, stopping, starting, restarting or upgrading.

Note: in some cases the operating system can force installation of critical updates immediately upon a state transition, or automatically restart a machine to install updates. In such cases the updatesPending property may not always be set accurately by the underlying os.

Examples
paperspace.machines.setAccessForUser({
  machineId: 'ps123abc',
  userId: 'u123abc,
}, function(err, res) {
  // handle error or result
});
$ paperspace machines setAccessForUser \
    --machineId "ps123abc" --userId "u12abc"
# HTTP request:
https://api.paperspace.io
GET /machines/:machineId/setMachineAccessPublic?userId=u123abc
x-api-key: 1ba4f98e7c0...
# Returns 200 on success
Parameters:
Name Type Description
params object

Machine show parameters

Properties
Name Type Description
machineId string

Id of the machine to show
userId string

Id of the user to enable machine access for
enabeAccess- boolean

releases any assigned public ip address for the machine; defaults to false
cb function

Node-style error-first callback function
Returns:

machine - The machine JSON object

Type
object

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

Source:

Show machine information for the machine with the given id.

The state property can take on the follow values:

  • off
  • starting - machine is in the process of changing to the ready or serviceready state
  • stopping - machine is in the process of changing to the off state
  • restarting - combines stopping follow immediately by starting
  • serviceready - services are running on the machine but the Paperspace agent is not yet available
  • ready - services are running on machine and the Paperspace agent is ready to stream or accept logins
  • upgrading - the machine specification are being upgraded, which involves a shutdown and startup sequence
  • provisioning - the machine is in the process of being created for the first time

The updatesPending property is either true or false and reflects whether the operating system has scheduled updates for the next machine state transition, e.g, stopping, starting, restarting or upgrading.

Note: in some cases the operating system can force installation of critical updates immediately upon a state transition, or automatically restart a machine to install updates. In such cases the updatesPending property may not always be set accurately by the underlying os.

Examples
paperspace.machines.show({
  machineId: 'ps123abc',
}, function(err, res) {
  // handle error or result
});
$ paperspace machines show \
    --machineId "ps123abc"
# HTTP request:
https://api.paperspace.io
GET /machines/getMachinePublic?machineId=ps123abc
x-api-key: 1ba4f98e7c0...
# Returns 200 on success
//Example return value:
{
  "id": "ps123abc",
  "name": "My Machine",
  "os": "Microsoft Windows Server 2016 Datacenter",
  "ram": "8589938688",
  "cpus": 4,
  "gpu": "GRID K160Q (2GB)",
  "storageTotal": "53687091200",
  "storageUsed": "110080",
  "usageRate": "Air monthly",
  "shutdownTimeoutInHours": 168,
  "shutdownTimeoutForces": false,
  "performAutoSnapshot": false,
  "autoSnapshotFrequency": null,
  "autoSnapshotSaveCount": null,
  "agentType": "WindowsDesktop",
  "dtCreated": "2016-11-18T05:18:29.533Z",
  "state": "ready",
  "updatesPending": false,
  "networkId": "n789ghi",
  "privateIpAddress": "10.64.21.47",
  "publicIpAddress": null,
  "region": "East Coast (NY2)",
  "userId": "u123abc",
  "teamId": "te456def",
  "scriptId": "sc123abc",
  "dtLastRun": "2017-06-30T07:22:49.763Z",
  "dynamicPublicIp": null,
  "events": [
    {
      "name": "start",
      "state": "done",
      "errorMsg": "",
      "handle": "8ebe43dd-57c8-4bd4-b770-86b7fd0202e4",
      "dtModified": "2017-08-16T14:36:24.802Z",
      "dtFinished": null,
      "dtCreated": "2017-08-16T14:36:18.373Z"
    },
    {
      "name": "start",
      "state": "error",
      "errorMsg": "Uh oh. This machine type can't start due to insufficient capacity or higher than normal demand. Please try again later.",
      "handle": "f6adb486-f5ae-4ab3-9a1a-51c19df5b337",
      "dtModified": "2017-06-09T15:32:38.115Z",
      "dtFinished": "2017-06-09T15:32:38.115Z",
      "dtCreated": "2017-06-09T15:32:37.019Z"
    },
    {
      "name": "stop",
      "state": "done",
      "errorMsg": "",
      "handle": "e352ad96-734f-4a26-8829-007c2f1d89f2",
      "dtModified": "2017-06-03T04:14:01.327Z",
      "dtFinished": null,
      "dtCreated": "2017-06-03T04:13:47.885Z"
    }
  ]
}
Parameters:
Name Type Description
params object

Machine show parameters

Properties
Name Type Description
machineId string

Id of the machine to show
cb function

Node-style error-first callback function
Returns:

machine - The machine JSON object

Type
object

(static) start(params, cb)

Source:

Start up an individual machine. If the machine is already started, this action is a no-op. If the machine is off, it will be booted up. This action can only be performed by the user who owns the machine.

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

Machine start parameters

Properties
Name Type Description
machineId string

Id of the machine to start
cb function

Node-style error-first callback function

(static) stop(params, cb)

Source:

Stop an individual machine. If the machine is already stopped or has been shut down, this action is a no-op. If the machine is running, it will be stopped and any users logged in will be immediately kicked out. This action can only be performed by the user who owns the machine.

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

Machine stop parameters

Properties
Name Type Description
machineId string

Id of the machine to shut down
cb function

Node-style error-first callback function

(static) update(params, cb)

Source:

Update attributes of a machine.

Examples
paperspace.machines.update({
  machineId: 'ps123abc',
  machineName: 'New Machine Name',
  shutdownTimeoutInHours: 24,
  shutdownTimeoutForces: true,
  performAutoSnapshot: true,
  autoSnapshotFrequency: 'week',
  autoSnapshotSaveCount: 4
}, function(err, res) {
  // handle error or result
});
$ paperspace machines update --machineId "ps123abc"
    --machineName "New Machine Name" \
    --shutdownTimeoutInHours 24 \
    --shutdownTimeoutForces true \
    --performAutoSnapshot true \
    --autoSnapshotFrequency "week" \
    --autoSnapshotSaveCount 4 \
    --dynamicPublicIp true
# HTTP request:
https://api.paperspace.io
POST /machines/ps123abc/updateMachinePublic {"machineId": "ps123abc", "machineName": "New Machine Name", "shutdownTimeoutInHours": 24, "shutdownTimeoutForces": true, "performAutoSnapshot": true, "autoSnapshotFrequency": "week", "autoSnapshotSaveCount": 4, "dynamicPublicIp": true}
x-api-key: 1ba4f98e7c0...
# Returns 204 on success
Parameters:
Name Type Description
params object

Machine update parameters

Properties
Name Type Attributes Description
machineId string

Id of the machine to update
machineName string <optional>

New name for the machine
shutdownTimeoutInHours number <optional>

Number of hours before machine is shutdown if no one is logged in via the Paperspace client
shutdownTimeoutForces boolean <optional>

Force shutdown at shutdown timeout, even if there is a Paperspace client connection
autoSnapshotFrequency number <optional>

One of 'hour', 'day', 'week', or null
autoSnapshotSaveCount number <optional>

Number of snapshots to save
performAutoSnapshot boolean <optional>

Perform auto snapshots
dynamicPublicIp boolean <optional>

If true, assigns a new public ip address on machine start and releases it from the account on machine stop
cb function

Node-style error-first callback function

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

Source:

Get machine utilization data for the machine with the given id. Machine upgrades are not represented in utilization data.

Examples
paperspace.machines.utilization({
  machineId: 'ps123abc',
  billingMonth: '2017-08',
}, function(err, res) {
  // handle error or result
});
$ paperspace machines utilization \
    --machineId "ps123abc" \
    --billingMonth "2017-08"
# HTTP request:
https://api.paperspace.io
GET /machines/getUtilization?machineId=ps123abc&billingMonth=2017-08
x-api-key: 1ba4f98e7c0...
# Returns 200 on success
//Example return value:
{
  "machineId": "ps123abc",
  "utilization": {
    "machineId": "ps123abc",
    "secondsUsed": 37351.08562622,
    "hourlyRate": "0.40",
    "billingMonth": "2017-08",
  },
  "storageUtilization": {
    "machineId": "ps123abc",
    "secondsUsed": 678400,
    "monthlyRate": "7.00",
    "billingMonth": "2017-08",
  }
}
Parameters:
Name Type Description
params object

Machine utilization parameters

Properties
Name Type Description
machineId string

Id of the machine to get utilization data for
billingMonth string

Billing period to query in YYYY-MM format
cb function

Node-style error-first callback function
Returns:

utilization - The utilization JSON object

Type
object

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

Source:

Wait for the machine with the given id to enter a certain machine state. This action polls the server and returns only when we detect that the machine has transitioned into the given state. States available to check for are:

  • off
  • serviceready - services are running on the machine but the Paperspace agent is not yet available
  • ready - services are running on machine and the Paperspace agent is ready to stream or accept logins

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

Examples
paperspace.machines.waitfor({
  machineId: 'ps123abc',
  state: 'off',
}, function(err, res) {
  // handle error or result
});
$ paperspace machines waitfor \
    --machineId "ps123abc" \
    --state "off"
# HTTP request:
# The waitefor method is only available using the API client.
# Use the show method to query the state of the machine via HTTP.
//Example return value:
{
  "id": "ps123abc",
  "name": "My Machine",
  "os": "Microsoft Windows Server 2016 Datacenter",
  "ram": "8589938688",
  "cpus": 4,
  "gpu": "GRID K160Q (2GB)",
  "storageTotal": "53687091200",
  "storageUsed": "110080",
  "usageRate": "Air monthly",
  "shutdownTimeoutInHours": 168,
  "shutdownTimeoutForces": false,
  "performAutoSnapshot": false,
  "autoSnapshotFrequency": null,
  "autoSnapshotSaveCount": null,
  "agentType": "WindowsDesktop",
  "dtCreated": "2016-11-18T05:18:29.533Z",
  "state": "ready",
  "updatesPending": false,
  "networkId": "n789ghi",
  "privateIpAddress": "10.64.21.47",
  "publicIpAddress": null,
  "region": "East Coast (NY2)",
  "userId": "u123abc",
  "teamId": "te456def",
  "scriptId": "sc123abc",
  "dtLastRun": "2017-06-30T07:22:49.763Z",
  "dynamicPublicIp": null
}
Parameters:
Name Type Description
params object

Machine waitfor parameters

Properties
Name Type Description
machineId string

Id of the machine to wait for
state string

Name of the state to wait for, either 'off', 'serviceready', 'ready'
cb function

Node-style error-first callback function
Returns:

machine - The machine JSON object

Type
object