Managing jobs in Serverless AI

Serverless AI jobs run container images as one-off or scheduled batch workloads. They are suitable for training, fine-tuning and data processing where you want to use computing resources only to perform a task and stop when the task is done. Each job runs on a Compute container virtual machine (VM) managed by Serverless AI and billed only while the job is running.

Prerequisites

Web console
CLI
REST API

Make sure you are in a group that has at least the editor role within your tenant or project; for example, the default editors group. You can check this in the Administration → IAM section of the web console.

Install and configure the Nebius AI Cloud CLI. Check that your project ID is saved in the Nebius AI Cloud CLI profile configuration:
cat ~/.nebius/config.yaml
Make sure you are in a group that has at least the editor role within your tenant or project; for example, the default editors group. You can check this in the Administration → IAM section of the web console.

Get an access token to authenticate to the REST API.
Make sure you are in a group that has at least the editor role within your tenant or project; for example, the default editors group. You can check this in the Administration → IAM section of the web console.

How to create a job

To run a container image as a batch workload for training, fine-tuning or data processing, create a job:

Web console
CLI
REST API

In the sidebar, go to Serverless AI → Jobs.
Click Create job.
In Configuration, select Custom.
Configure Job settings:
1. In Image path, set the path to the container image.
2. If you use a private registry, in Private registry, select an existing registry or click Add, and provide the details for your registry.
3. (Optional) In Entrypoint command, specify the entrypoint command for the container. If you need to pass container arguments, specify them in this field as well.
4. (Optional) In Environment variables, specify environment variables in key-value pairs.
5. (Optional) In Secret environment variables, specify environment variables so that API keys and other credentials aren’t hardcoded in configs or CI scripts.
6. (Optional) In Job timeout in hours, specify the number of hours after which the job will be canceled if not completed.
(Optional) Configure the Computing resources section:
1. Select whether the container VM should have GPUs.
2. Specify the VM type: regular or preemptible. VMs without GPUs only support the regular type.
3. Select the platform and preset.
(Optional) Configure Storage settings:
- Under Container disk, set Size. See how disk performance depends on disk size.
- Under Mounted volumes, click Attach volume to attach a bucket or a filesystem. You can create a bucket or filesystem, or use an existing one. To create a new bucket, see Bucket parameters. To create a new filesystem, see Volume parameters.
(Optional) In the Access section, configure User name and SSH key to connect to the running workload for debugging. You can create new credentials or select existing ones. If you decide to use an existing credential, make sure that the SSH key is stored for the nebius username.
Configure the Network section:
- Select a subnet or create a new one.
- Select the IP address type: Public static IP or Private IP. If you want to connect to the resource from the internet, select Public static IP.
Click Create job.

With the command below, you specify all values directly in the command. This is useful for scripts, configuration-driven workflows, continuous integration (CI) and agents. Alternatively, you can run nebius ai create to use the interactive flow where the CLI prompts you for parameter values step by step.

Run the following command:

nebius ai job create \
  --name <job_name> \
  --image <image_path> \
  --registry-username <username> \
  --registry-password <password> \
  --container-command "<command>" \
  --args "<arguments>" \
  --env <key=value> \
  --working-dir <absolute_path> \
  --timeout <duration> \
  --platform <platform_ID> \
  --preset <preset> \
  --disk-size <size> \
  --volume <source:container_path[:mode]|s3://bucket:/container_path[:mode[:profile]]> \
  --inject-file "<local_path>:<absolute_container_path>" \
  --subnet-id <subnet_ID> \
  --shm-size <size> \
  --ssh-key <SSH_public_key> \
  --preemptible

Job creation example

nebius ai job create \
  --name training-job \
  --image nvidia/cuda:13.1.1-runtime-ubuntu24.04 \
  --container-command bash \
  --args "-c nvidia-smi" \
  --platform gpu-l40s-a \
  --preset 1gpu-8vcpu-32gb \
  --timeout 1h \
  --subnet-id vpcsubnet-e***

In the command, specify the following parameters:

Job settings:
- --name: Job name.
- --image: Container image reference in the registry/path:tag or registry/path@digest format. Use an image from a public registry or your authenticated private registry.
- --registry-username, --registry-password (optional): Credentials to authenticate if you pull an image from a private registry. Alternatively, use --registry-secret for credentials stored in SecretStash.
  - --registry-username: Username.
  - --registry-password: Personal access token, password or an API key. Depends on where your registry is hosted. It can be Docker Hub, Microsoft Azure, GitHub, NVIDIA or a custom registry.
  If you pull an image from a public registry or from Container Registry in the same project, you don’t need to specify credentials.
- --registry-secret (optional): SecretStash secret selector with REGISTRY_USERNAME and REGISTRY_PASSWORD payload keys. You can specify a secret name, secret ID, version ID or a combined secret/version selector such as mbsec-e00***@mbsecver-e00***.
- --container-command (optional): Entrypoint command for the container.
- --args (optional): Arguments for docker run to pass to the entrypoint command.
- --env (optional): Environment variables for the container. Set them in the key=value format where the key is the environment variable and the value is the value of this variable. If you need to set several variables, list the key=value pairs separated by commas.
- --env-secret (optional): Environment variables loaded from a SecretStash secret in the key=value format. The value can be a secret name, secret ID, version ID or a combined secret/version selector such as mbsec-e00***@mbsecver-e00***. If you need to set several variables, list the pairs separated by commas.
- --working-dir (optional): Working directory (absolute path).
- --timeout (optional): Job timeout (for example, 2h30m10s, 24h). Minimum: 1h, maximum: 168h. Default: 24h.
- --inject-file (optional): Mount a local file into the job container at launch. Use the format <local_path>:<absolute_container_path>. To inject multiple files, repeat the parameter. The mounted file is read-only and limited to 64 KiB.
- --volume (optional): Bucket or shared filesystem to mount to the job container and to store the job results and checkpoints. Volumes persist if the job is recreated after a maintenance event. Specify the value in either format:
  - source:container_path[:mode] for mounting Nebius shared filesystems and existing bucket or volume resources by ID or name.
  - s3://bucket:/container_path[:mode[:profile]] for mounting an Object Storage bucket with AWS profile credentials or S3 credentials stored in SecretStash. The profile is the AWS credentials profile to use. If you manage your credentials with SecretStash, use profile@<secret_selector>, where <secret_selector> is a secret name, secret ID, version ID or a combined secret/version selector such as mbsec-e00***@mbsecver-e00***
  The supported modes are ro, read only, and rw, read-write (default). Repeat for multiple volumes. For example:
  --volume 'computefilesystem-e***:/input:ro' \ --volume 'storagebucket-e***:/output:rw' \ --volume 's3://training-results:/output:rw:default'
Underlying container VM characteristics:
- --subnet-id: Subnet ID. Required if the project has multiple subnets.
- --platform: VM platform. See available platforms in Types of virtual machines and GPUs in Nebius AI Cloud.
- --preset: Number of GPUs, vCPUs and RAM allocated to the container. The preset must match the selected platform. See available presets in Presets for GPU platforms.
- --disk-size: Disk size of the container VM. Specify the value such as 100Gi, 500Gi or 1Ti. The default value is 250Gi. See how disk performance depends on disk size.
- --shm-size (optional): Shared memory size of /dev/shm. Specify the value such as 64Mi, 128Mi or 1Gi. The default value is 16Gi.
- --ssh-key (optional): SSH key to access the container VM by SSH. When you add an SSH key, a public dynamic IP address is assigned. Before you add the key, check the quota on the number of public IP addresses in the web console.
- --preemptible (optional): Use a preemptible VM. Preemptible VMs are cheaper but can be stopped by Compute at any time. Only GPU platforms offer preemptible VMs. If you omit this parameter, the container runs on a regular VM.

Send the following request:

curl --request POST \
  --url 'https://api.nebius.cloud/ai/v1/jobs' \
  --header "Authorization: Bearer <access_token>" \
  --header 'Content-Type: application/json' \
  --data '{
    "metadata": {
      "parentId": "<project_ID>",
      "name": "my-job-1"
    },
    "spec": {
      "image": "<image_path>",
      "registryCredentials": {"username": "<username>", "password": "<password>"},
      "containerCommand": "<command>",
      "args": "<arguments>",
      "environmentVariables": [
        {
          "name": "<environment_variable_name>",
          "value": "<environment_variable_value>"
        }
      ],
      "workingDir": "<absolute_path>",
      "timeout": "<duration>",
      "platform": "<platform_ID>",
      "preset": "<preset>",
      "disk": {
        "type": "NETWORK_SSD",
        "sizeBytes": "<disk_size_in_bytes>"
      },
      "volumes": [
        {
          "source": "<volume_ID_or_name>",
          "containerPath": "<absolute_container_path>",
          "mode": "<READ_ONLY_or_READ_WRITE>"
        }
      ],
      "injectedFiles": [
        {
          "containerPath": "<absolute_container_path>",
          "content": "<base64_encoded_file_content>"
        }
      ],
      "shmSizeBytes": "<shared_memory_size_in_bytes>",
      "sshAuthorizedKeys": [
        "<SSH_public_key>"
      ],
      "subnetId": "<subnet_ID>",
      "preemptible": true
    }
  }'

Job creation example

curl --request POST \
  --url 'https://api.nebius.cloud/ai/v1/jobs' \
  --header "Authorization: Bearer <access_token>" \
  --header 'Content-Type: application/json' \
  --data '{
    "metadata": {
      "parentId": "<project_ID>",
      "name": "training-job"
    },
    "spec": {
      "image": "nvidia/cuda:13.1.1-runtime-ubuntu24.04",
      "containerCommand": "bash",
      "args": "-c nvidia-smi",
      "platform": "gpu-l40s-a",
      "preset": "1gpu-8vcpu-32gb",
      "timeout": "3600s",
      "subnetId": "vpcsubnet-e***",
      "disk": {
        "type": "NETWORK_SSD",
        "sizeBytes": "268435456000"
      }
    }
  }'

In the Authorization header, replace <access_token> with the access token that you got in the prerequisites.The request includes the following parameters:

Job settings:
- metadata.parentId: Project ID.
- metadata.name: Job name.
- spec.image: Container image reference in the registry/path:tag or registry/path@digest format. Use an image from a public registry or your authenticated private registry.
- spec.registryCredentials (optional): Credentials to authenticate if you pull an image from a private registry.
  - spec.registryCredentials.username: Username.
  - spec.registryCredentials.password: Personal access token, password or an API key. Depends on where your registry is hosted. It can be Docker Hub, Microsoft Azure, GitHub, NVIDIA or a custom registry.
  If you pull an image from a public registry or from Container Registry in the same project, you don’t need to specify credentials.
- spec.containerCommand (optional): Entrypoint command for the container.
- spec.args (optional): Arguments for docker run to pass to the entrypoint command.
- spec.environmentVariables (optional): Environment variables for the container.
  - spec.environmentVariables[].name: Environment variable name.
  - spec.environmentVariables[].value: Environment variable value.
- spec.workingDir (optional): Working directory (absolute path).
- spec.timeout (optional): Job timeout in seconds with the s suffix (for example, 9000s). Minimum: 3600s (1 hour), maximum: 604800s (168 hours). Default: 86400s (24 hours).
- spec.volumes (optional): Buckets or shared filesystems to mount to the job container and to store the job results and checkpoints. Volumes persist if the job is recreated after a maintenance event.
  - spec.volumes[].source: Volume ID or name.
  - spec.volumes[].containerPath: Absolute path where the volume is mounted in the container.
  - spec.volumes[].mode: Mount mode: READ_ONLY or READ_WRITE.
- spec.injectedFiles (optional): Files to mount into the job container at launch. To inject multiple files, add multiple items. Each mounted file is read-only and limited to 64 KiB.
  - spec.injectedFiles[].containerPath: Absolute path where the file is mounted in the container.
  - spec.injectedFiles[].content: Base64-encoded file content.
Underlying container VM characteristics:
- spec.subnetId: Subnet ID. Required if the project has multiple subnets.
- spec.platform: VM platform. See available platforms in Types of virtual machines and GPUs in Nebius AI Cloud.
- spec.preset: Number of GPUs, vCPUs and RAM allocated to the container. The preset must match the selected platform. See available presets in Presets for GPU platforms.
- spec.disk.type: Disk type for the container VM.
- spec.disk.sizeBytes: Disk size of the container VM in bytes. The default value is 250 GiB. See how disk performance depends on disk size.
- spec.shmSizeBytes (optional): Shared memory size of /dev/shm in bytes. The default value is 16 GiB.
- spec.sshAuthorizedKeys (optional): SSH public keys to access the container VM by SSH. When you add an SSH key, a public dynamic IP address is assigned. Before you add the key, check the quota on the number of public IP addresses in the web console.
- spec.preemptible (optional): Whether to use a preemptible VM. Preemptible VMs are cheaper but can be stopped by Compute at any time. Only GPU platforms offer preemptible VMs. If omitted or set to false, the container runs on a regular VM.

The job creation usually takes a few minutes. Jobs run until the workload finishes. When the job completes successfully or fails, the container VM is deleted automatically. If you mounted volumes, they will remain, and you should delete them manually.

How to check job logs

For this operation, it’s enough to be in a group that has the viewer role within your tenant; for example, the default viewers group. You can check this in the Administration → IAM section of the web console.

Checking job logs is available only in the web console and CLI.

Web console
CLI

In the sidebar, go to Serverless AI → Jobs.
Next to the job, click View logs. Alternatively, select the job that you want to view the logs for and switch to the Logs tab.

You can use the period or log level filters to filter the logs. You can also use the LogQL query language.

Run the following command:

nebius ai job logs <job_ID> --follow

You can add the following parameters to control the output:

--follow or -f: Stream logs in real time.
--since <value>: Show logs starting from the specified time. For example, 1h (from 1 hour ago), 30m (from 30 minutes ago) or 2024-01-01 (from that date).
--tail <value>: Number of recent lines to show in the output.
--timestamps: Include timestamps in the output.
--until <value>: Show logs up to the specified time. For example, 1h (up to 1 hour ago), 30m (up to 30 minutes ago) or 2024-01-01 (up to that date).

How to cancel a job

If you don’t need a job to continue running, you can cancel it. The jobs that finish with COMPLETED status are canceled automatically. To cancel a job:

Web console
CLI
REST API

In the sidebar, go to Serverless AI → Jobs.
Find the job and then click → Cancel.
In the window that opens, confirm canceling the job.

List jobs:
nebius ai job list
In the output, copy the ID of the required job.
To cancel a job, run:
nebius ai job cancel <job_ID>

List jobs:
curl --request GET \ --url "https://api.nebius.cloud/ai/v1/jobs?parentId=<project_ID>" \ --header "Authorization: Bearer <access_token>"
In the request, specify:
- Your access token in the Authorization header.
- The project ID in the parentId query parameter.
In the response, copy the metadata.id of the required job.

Cancel the job:

curl --request POST \
  --url 'https://api.nebius.cloud/ai/v1/jobs/cancel' \
  --header "Authorization: Bearer <access_token>" \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "<job_ID>"
  }'

In the request, specify:

Your access token in the Authorization header.
<job_ID>: Job ID that you copied.

Canceling a job immediately stops the container VM and deletes the container disk. The job remains in the list of jobs. Mounted volumes are retained. You can remove the mounted volumes manually. See the guides on deleting a filesystem and deleting a bucket. If you need to remove any record about the job from the job list, delete the job instead of canceling it.

How to delete a job

To delete a job:

Web console
CLI
REST API

In the sidebar, go to Serverless AI → Jobs.
Locate the job and then click → Delete.
In the window that opens, confirm deleting the job.

List jobs:
nebius ai job list
In the output, copy the ID of the required job.
Delete the job:
nebius ai job delete <job_ID>

List jobs:
curl --request GET \ --url "https://api.nebius.cloud/ai/v1/jobs?parentId=<project_ID>" \ --header "Authorization: Bearer <access_token>"
In the request, specify:
- Your access token in the Authorization header.
- The project ID in the parentId query parameter.
In the response, copy the metadata.id of the required job.

Delete the job:

curl --request DELETE \
  --url "https://api.nebius.cloud/ai/v1/jobs/<job_ID>" \
  --header "Authorization: Bearer <access_token>"

In the request, specify:

Your access token in the Authorization header.
The job ID that you copied in the request path.

When the job is deleted, it disappears from the list of jobs. If a job is running, deleting cancels the job first. If the job uses additional volumes, they are not deleted with it. You can remove the mounted volumes manually. See the guides on deleting a filesystem and deleting a bucket.

AI services in Nebius AI Cloud

Serverless AI

Managed Service for MLflow

Applications in Nebius AI Cloud

Tutorials

Third-party integrations

Managing jobs in Serverless AI

Prerequisites

How to create a job

How to check job logs

How to cancel a job

How to delete a job

​Prerequisites

​How to create a job

​How to check job logs

​How to cancel a job

​How to delete a job

Prerequisites

How to create a job

How to check job logs

How to cancel a job

How to delete a job