Kernel Management

Here are the API calls to create and manage compute sessions.

Creating Kernel Session

  • URI: /kernel (/kernel/create also works for legacy)

  • Method: POST

Creates a kernel session if there is no existing (running) kernel with the same clientSessionToken. If there is an existing session and it has the same lang, no new session is created but the API returns successfully. In this case, config options are ignored and the created field in the response is set false (otherwise it’s true). If there is an existing session but with a different lang, then the API server returns an error.

Parameters

Parameter

Type

Description

image

str

The kernel runtime type in the form of the Docker image name and tag. For legacy, the API also recognizes the lang field when image is not present.

Changed in version v4.20190315.

clientSessionToken

slug

A client-provided session token, which must be unique among the currently non-terminated sessions owned by the requesting access key. Clients may reuse the token if the previous session with the same token has been terminated.

It may contain ASCII alphabets, numbers, and hyphens in the middle. The length must be between 4 to 64 characters inclusively. It is useful for aliasing the session with a human-friendly name.

config

object

(optional) A Creation Config Object to specify kernel configuration including resource requirements. If not given, the kernel is created with the minimum required resource slots defined by the target image.

tag

str

(optional) A per-session, user-provided tag for administrators to keep track of additional information of each session, such as which sessions are from which users.

Example:

{
  "image": "python:3.6-ubuntu18.04",
  "clientSessionToken": "mysession-01",
  "config": {
    "clusterSize": 1,
    "environ": {
      "MYCONFIG": "XXX",
    },
    "mounts": ["mydata", "mypkgs"],
    "resources": {
      "cpu": "2",
      "mem": "4g",
      "cuda.devices": "1",
    }
  },
  "tag": "example-tag"
}

Response

HTTP Status Code

Description

201 Created

The kernel is successfully created.

406 Not acceptable

The requested resource limits exceed the server’s own limits.

Fields

Type

Values

kernelId

slug

The kernel ID used for later API calls, which is same to the value of clientSessionToken. This will be random-generated by the server if clientSessionToken is not provided.

servicePorts

list[object]

The list of Service Port Object.

created

bool

True if the kernel is freshly created.

Example:

{
  "kernelId": "mysession-01",
  "servicePorts": [
    {"name": "jupyter", "protocol": "http"},
    {"name": "tensorboard", "protocol": "http"}
  ],
  "created": true
}

Getting Kernel Information

  • URI: /kernel/:id

  • Method: GET

Retrieves information about a kernel session. For performance reasons, the returned information may not be real-time; usually they are updated every a few seconds in the server-side.

Parameters

Parameter

Type

Description

:id

slug

The kernel ID.

Response

HTTP Status Code

Description

200 OK

The information is successfully returned.

404 Not Found

There is no such kernel.

Key

Type

Description

lang

str

The kernel’s programming language

age

int (msec)

The time elapsed since the kernel has started.

memoryLimit

int (KiB)

The memory limit of the kernel in KiB.

numQueriesExecuted

int

The number of times the kernel has been accessed.

cpuCreditUsed

int (msec)

The total time the kernel was running.

Destroying Kernel Session

  • URI: /kernel/:id

  • Method: DELETE

Terminates a kernel session.

Parameters

Parameter

Type

Description

:id

slug

The kernel ID.

Response

HTTP Status Code

Description

204 No Content

The kernel is successfully destroyed.

404 Not Found

There is no such kernel.

Key

Type

Description

stats

object

The Container Stats Object of the kernel when deleted.

Restarting Kernel Session

  • URI: /kernel/:id

  • Method: PATCH

Restarts a kernel session. The idle time of the kernel will be reset, but other properties such as the age and CPU credit will continue to accumulate. All global states such as global variables and modules imports are also reset.

Parameters

Parameter

Type

Description

:id

slug

The kernel ID.

Response

HTTP Status Code

Description

204 No Content

The kernel is successfully restarted.

404 Not Found

There is no such kernel.