machines

Note

A new Paperspace API is now available. The Gradient and Core API endpoints will become unavailable on 15 July, 2024. For more information, see the release notes.

Core machines are Linux and Windows-based virtual machines (VMs) that run on top of virtualized hardware. Each machine you create is a new server or desktop instance you can use, either standalone or as part of a larger, cloud-based infrastructure.

Note

As of 1 July 2024, Windows templates are retired and as a result unavailable to new Paperspace users. Users who joined Paperspace prior to this date can still start, manage, and create Window template machines.

create

This command creates a new Paperspace virtual machine.

If you are using an individual account, you are 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 specifying 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.

Only account administrators may create machines. Team members cannot create machines themselves.

Examples

paperspace machines create \
  --apiKey "edc20a51d9b2145..." \
  --region "East Coast (NY2)" \
  --machineType "P4000" \
  --size 50 \
  --billingType "hourly" \
  --machineName "My Machine 1" \
  --templateId "tbu200wi" \
  --teamId "tewr3st2z"

curl -X POST 'https://api.paperspace.io/machines/createSingleMachinePublic' \
-H 'X-Api-Key: edc20a51d9b2145...' \
-H 'Content-Type: application/json' \
--data-raw '{
  "region": "East Coast (NY2)",
  "machineType": "P4000",
  "size": 50,
  "billingType": "hourly",
  "machineName": "My Machine 1",
  "templateId": "tbu200wi",
  "teamId": "tewr3st2z"
}'

paperspace.machines.create(
  {
    region: "East Coast (NY2)",
    machineType: "P4000",
    size: 50,
    billingType: "hourly",
    machineName: "My Machine 1",
    templateId: "tbu200wi",
    teamId: "tewr3st2z",
  },
  function (err, res) {
    // handle error or result
  }
);

Parameters

Response

The created machine JSON object

{
  "id": "psazmnxdy",
  "name": "My Machine 1",
  "os": null,
  "ram": null,
  "cpus": 1,
  "gpu": null,
  "storageTotal": null,
  "storageUsed": null,
  "machineType": "P4000",
  "usageRate": "P4000 hourly",
  "shutdownTimeoutInHours": 168,
  "shutdownTimeoutForces": false,
  "performAutoSnapshot": false,
  "autoSnapshotFrequency": null,
  "autoSnapshotSaveCount": null,
  "dynamicPublicIp": false,
  "agentType": "LinuxHeadless",
  "dtCreated": "2022-03-14T15:09:51.974Z",
  "state": "provisioning",
  "updatesPending": false,
  "networkId": null,
  "privateIpAddress": null,
  "publicIpAddress": null,
  "region": null,
  "scriptId": null,
  "dtLastRun": null,
  "restorePointSnapshotId": null,
  "restorePointFrequency": null
}

start

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

Examples

paperspace machines start \
  --apiKey "edc20a51d9b2145..." \
  --machineId "psfj3c701"

curl -X POST 'https://api.paperspace.io/machines/psfj3c701/start' \
-H 'X-Api-Key: edc20a51d9b2145...'

paperspace.machines.start(
  {
    machineId: "psfj3c701",
  },
  function (err, res) {
    // handle error or result
  }
);

Parameters

stop

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 is stopped and any users logged in are immediately kicked out. This action can only be performed by the user who owns the machine.

Examples

paperspace machines stop \
  --apiKey "edc20a51d9b2145..." \
  --machineId "psfj3c701"

curl -X POST 'https://api.paperspace.io/machines/psfj3c701/stop' \
-H 'X-Api-Key: edc20a51d9b2145...'

paperspace.machines.stop(
  {
    machineId: "psfj3c701",
  },
  function (err, res) {
    // handle error or result
  }
);

Parameters

restart

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

Examples

paperspace machines restart \
  --apiKey "edc20a51d9b2145..." \
  --machineId "psfj3c701"

curl -X POST 'https://api.paperspace.io/machines/psfj3c701/restart' \
-H 'X-Api-Key: edc20a51d9b2145...'

paperspace.machines.stop(
  {
    machineId: "psfj3c701",
  },
  function (err, res) {
    // handle error or result
  }
);

Parameters

destroy

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 \
  --apiKey "edc20a51d9b2145..." \
  --machineId "psfj3c701"

curl -X POST 'https://api.paperspace.io/machines/psfj3c701/destroyMachine' \
-H 'X-Api-Key: edc20a51d9b2145...'

paperspace.machines.destroy(
  {
    machineId: "psfj3c701",
  },
  function (err, res) {
    // handle error or result
  }
);

Parameters

update

Update attributes of a machine.

Examples

paperspace machines update \
  --apiKey "edc20a51d9b2145..." \
  --machineId "psec02yp2" \
  --machineName "New Machine Name"

curl -X POST 'https://api.paperspace.io/machines/psec02yp2/updateMachinePublic' \
-H 'X-Api-Key: edc20a51d9b2145...' \
-H 'Content-Type: application/json' \
--data-raw '{"machineName": "New Machine Name"}'

paperspace.machines.update(
  {
    machineId: "psec02yp2",
    machineName: "New Machine Name",
  },
  function (err, res) {
    // handle error or result
  }
);

Parameters

list

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.

This API supports pagination using limit and skip. The default limit is 1000 items. To retrieve more than 1000 items, set your skip parameter to a multiple of 1000. For example, to retrieve the 3rd page of 1000 items, you would pass { limit: 1000, skip: 2000 }.

Examples

paperspace machines list \
  --apiKey "edc20a51d9b2145..."

curl -X GET 'https://api.paperspace.io/machines/getMachines' \
-H 'X-Api-Key: edc20a51d9b2145...'

paperspace.machines.list(function (err, res) {
  // handle error or result
});

Parameters

Response

[
  {
    "id": "psec02yp2",
    "name": "New Machine Name1",
    "os": "",
    "ram": "32212254720",
    "cpus": 8,
    "gpu": "Quadro P4000",
    "storageTotal": "53687091200",
    "storageUsed": "110080",
    "machineType": "P4000",
    "usageRate": "P4000 hourly",
    "shutdownTimeoutInHours": 24,
    "shutdownTimeoutForces": false,
    "performAutoSnapshot": false,
    "autoSnapshotFrequency": "day",
    "autoSnapshotSaveCount": 1,
    "dynamicPublicIp": false,
    "agentType": "LinuxDesktop",
    "dtCreated": "2022-03-14T15:47:53.852Z",
    "state": "ready",
    "updatesPending": false,
    "networkId": "nng82wb",
    "privateIpAddress": "10.64.1.99",
    "publicIpAddress": "172.83.15.54",
    "region": "East Coast (NY2)",
    "scriptId": null,
    "dtLastRun": null,
    "restorePointSnapshotId": null,
    "restorePointFrequency": null,
    "internalId": 1713423
  }
]

show

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 \
  --apiKey "edc20a51d9b2145..." \
  --machineId "psec02yp2"

curl -X GET 'https://api.paperspace.io/machines/getMachinePublic?machineId=psec02yp2' \
-H 'X-Api-Key: edc20a51d9b2145...'

paperspace.machines.show(
  {
    machineId: "psec02yp2",
  },
  function (err, res) {
    // handle error or result
  }
);

Parameters

Response

machine - The machine JSON object

Type object

{
  "id": "psec02yp2",
  "name": "New Machine Name1",
  "os": "",
  "ram": "32212254720",
  "cpus": 8,
  "gpu": "Quadro P4000",
  "storageTotal": "53687091200",
  "storageUsed": "110080",
  "machineType": "P4000",
  "usageRate": "P4000 hourly",
  "shutdownTimeoutInHours": 24,
  "shutdownTimeoutForces": false,
  "performAutoSnapshot": false,
  "autoSnapshotFrequency": "day",
  "autoSnapshotSaveCount": 1,
  "dynamicPublicIp": false,
  "agentType": "LinuxDesktop",
  "dtCreated": "2022-03-14T15:47:53.852Z",
  "state": "ready",
  "updatesPending": false,
  "networkId": "nng82wb",
  "privateIpAddress": "10.64.1.99",
  "publicIpAddress": "172.83.15.54",
  "region": "East Coast (NY2)",
  "scriptId": null,
  "dtLastRun": null,
  "restorePointSnapshotId": null,
  "restorePointFrequency": null,
  "events": [
    {
      "name": "start",
      "state": "done",
      "errorMsg": "",
      "handle": "fabd398a-9c8e-4565-95fa-5f07928564d8",
      "dtModified": "2022-03-14T15:49:00.734Z",
      "dtFinished": "2022-03-14T15:49:00.734Z",
      "dtCreated": "2022-03-14T15:48:30.994Z"
    },
    {
      "name": "create",
      "state": "done",
      "errorMsg": "",
      "handle": "396ea947-9c10-4b63-a15b-574a9a9844bc",
      "dtModified": "2022-03-14T15:48:31.026Z",
      "dtFinished": "2022-03-14T15:48:31.026Z",
      "dtCreated": "2022-03-14T15:47:53.852Z"
    }
  ]
}

setAccessForUser

Examples

paperspace machines setAccessForUser \
  --apiKey "edc20a51d9b2145..." \
  --machineId "psec02yp2" \
  --userId "ubx9ce8k" \
  --enableAccess true

curl -X POST 'https://api.paperspace.io/machines/psec02yp2/setMachineAccess' \
  -H 'X-Api-Key: edc20a51d9b2145...' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "userId": "ubx9ce8k",
    "enableAccess": "true"
  }'

paperspace.machines.setAccessForUser(
  {
    machineId: "psec02yp2",
    userId: "ubx9ce8k",
    enableAccess: true,
  },
  function (err, res) {
    // handle error or result
  }
);

Parameters

utilization

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

Examples

paperspace machines utilization \
  --apiKey "edc20a51d9b2145..." \
  --machineId "psec02yp2" \
  --billingMonth "2022-03"

curl -X GET 'https://api.paperspace.io/machines/getUtilization?machineId=psec02yp2&billingMonth=2022-03' \
-H 'X-Api-Key: edc20a51d9b2145...'

paperspace.machines.utilization(
  {
    machineId: "psec02yp2",
    billingMonth: "2022-03",
  },
  function (err, res) {
    // handle error or result
  }
);

Parameters

Response

utilization - The utilization JSON object

Type object

{
  "machineId": "psec02yp2",
  "utilization": {
    "machineId": "psec02yp2",
    "secondsUsed": 8728.27191281319,
    "hourlyRate": "0.51",
    "billingMonth": "2022-03"
  },
  "storageUtilization": {
    "machineId": "psec02yp2",
    "secondsUsed": 8785.19808006287,
    "monthlyRate": "5.00",
    "billingMonth": "2022-03"
  }
}

waitFor

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 is information about the machine.

Examples

paperspace machines waitfor \
  --apiKey "edc20a51d9b2145..." \
  --machineId "psec02yp2" \
  --state "ready"

This method is not available via curl.

paperspace.machines.waitfor(
  {
    machineId: "psec02yp2",
    state: "ready",
  },
  function (err, res) {
    // handle error or result
  }
);

Parameters

Response

machine - The machine JSON object

Type object

{
  "id": "psec02yp2",
  "name": "New Machine Name1",
  "os": "",
  "ram": "32212254720",
  "cpus": 8,
  "gpu": "Quadro P4000",
  "storageTotal": "53687091200",
  "storageUsed": "110080",
  "machineType": "P4000",
  "usageRate": "P4000 hourly",
  "shutdownTimeoutInHours": 24,
  "shutdownTimeoutForces": false,
  "performAutoSnapshot": false,
  "autoSnapshotFrequency": "day",
  "autoSnapshotSaveCount": 1,
  "dynamicPublicIp": false,
  "agentType": "LinuxDesktop",
  "dtCreated": "2022-03-14T15:47:53.852Z",
  "state": "ready",
  "updatesPending": false,
  "networkId": "nng82wb",
  "privateIpAddress": "10.64.1.99",
  "publicIpAddress": "172.83.15.54",
  "region": "East Coast (NY2)",
  "scriptId": null,
  "dtLastRun": null,
  "restorePointSnapshotId": null,
  "restorePointFrequency": null,
  "events": [
    {
      "name": "start",
      "state": "done",
      "errorMsg": "",
      "handle": "fabd398a-9c8e-4565-95fa-5f07928564d8",
      "dtModified": "2022-03-14T15:49:00.734Z",
      "dtFinished": "2022-03-14T15:49:00.734Z",
      "dtCreated": "2022-03-14T15:48:30.994Z"
    },
    {
      "name": "create",
      "state": "done",
      "errorMsg": "",
      "handle": "396ea947-9c10-4b63-a15b-574a9a9844bc",
      "dtModified": "2022-03-14T15:48:31.026Z",
      "dtFinished": "2022-03-14T15:48:31.026Z",
      "dtCreated": "2022-03-14T15:47:53.852Z"
    }
  ]
}

availability

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 \
  --apiKey "edc20a51d9b2145..." \
  --region "East Coast (NY2)" \
  --machineType "P4000"

curl -X GET 'https://api.paperspace.io/machines/getAvailability?region=East%20Coast%20(NY2)&machineType=P4000' \
-H 'X-Api-Key: edc20a51d9b2145...'

paperspace.machines.availability(
  {
    region: "East Coast (NY2)",
    machineType: "P4000",
  },
  function (err, res) {
    // handle error or result
  }
);

Parameters

Response

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

{
  "available": true
}