Workloads V2

The Workloads V2 API allows you to create, retrieve, and delete workloads that originate from third-party ML frameworks, tools, or the broader Kubernetes ecosystem. These workloads are registered in the platform through the Workload Types API, some are already registered in NVIDIA Run:ai, while others can be added by administrators. Each submission combines the user's Kubernetes manifest with NVIDIA Run:ai scheduling metadata, enabling consistent orchestration, monitoring, and governance. See Extending workload support for more details.

Create a workload.

post

Submit a workload with metadata and a Kubernetes manifest.

Authorizations

AuthorizationstringRequired

Bearer authentication

Query parameters

dryRunbooleanOptional

True to perform validations only, without side effects.

Default: falseExample: false

Body

manifestBase64Encodedstring · byte · max: 2097152Optional

Kubernetes YAML manifest encoded in base 64. Mutually exclusive with manifest.

Example:

YXBpVmVyc2lvbjogdjEKa2luZDogUG9kCm1ldGFkYXRhOgogIG5hbWU6IG15LXBvZApzcGVjOgogIGNvbnRhaW5lcnM6CiAgLSBuYW1lOiBuZ2lueAogICAgaW1hZ2U6IG5naW54OmxhdGVzdAo=

Responses

202

Workload creation request accepted.

application/json

desiredPhasestring · enumRequired

The desired phase of the workload.

Possible values:

400

Bad request.

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

409

The specified resource already exists

application/json

500

unexpected error

application/json

503

unexpected error

application/json

post/api/v2/workloads

POST /api/v2/workloads HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 738

{
  "metadata": {
    "name": "my-workload-name",
    "useGivenNameAsPrefix": true,
    "projectId": 1,
    "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
    "priority": "text",
    "category": "text",
    "preemptibility": "preemptible",
    "configuration": {
      "mnnvl": "text",
      "userCredentials": {
        "sources": [
          {
            "ref": "my-hf-token-abc1234567"
          }
        ]
      }
    }
  },
  "manifest": {
    "apiVersion": "apps/v1",
    "kind": "Deployment",
    "metadata": {
      "name": "my-app"
    },
    "spec": {
      "replicas": 1,
      "selector": {
        "matchLabels": {
          "app": "my-app"
        }
      },
      "template": {
        "metadata": {
          "labels": {
            "app": "my-app"
          }
        },
        "spec": {
          "containers": [
            {
              "name": "app",
              "image": "nginx:latest"
            }
          ]
        }
      }
    }
  },
  "manifestBase64Encoded": "YXBpVmVyc2lvbjogdjEKa2luZDogUG9kCm1ldGFkYXRhOgogIG5hbWU6IG15LXBvZApzcGVjOgogIGNvbnRhaW5lcnM6CiAgLSBuYW1lOiBuZ2lueAogICAgaW1hZ2U6IG5naW54OmxhdGVzdAo="
}

{
  "metadata": {
    "name": "my-workload-name",
    "projectId": 1,
    "priority": "text",
    "category": "text",
    "preemptibility": "preemptible",
    "configuration": {
      "mnnvl": "text",
      "userCredentials": {
        "sources": [
          {
            "ref": "my-hf-token-abc1234567"
          }
        ]
      }
    },
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "gvk": {
      "group": "apps",
      "version": "v1",
      "kind": "Deployment"
    },
    "projectName": "project-a",
    "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
    "tenantId": 1001,
    "departmentId": 2,
    "departmentName": "default",
    "createdAt": "2024-01-15T10:30:00Z",
    "createdBy": "user@run.ai",
    "updatedAt": "2024-01-15T10:35:00Z",
    "updatedBy": "user@run.ai",
    "deletedAt": "2024-01-15T10:35:00Z",
    "deletedBy": "user@run.ai"
  },
  "desiredPhase": "Running",
  "workloadManifest": {
    "apiVersion": "apps/v1",
    "kind": "Deployment",
    "metadata": {
      "name": "my-app"
    },
    "spec": {
      "replicas": 1,
      "selector": {
        "matchLabels": {
          "app": "my-app"
        }
      },
      "template": {
        "metadata": {
          "labels": {
            "app": "my-app"
          }
        },
        "spec": {
          "containers": [
            {
              "name": "app",
              "image": "nginx:latest"
            }
          ]
        }
      }
    }
  },
  "rawManifest": {
    "apiVersion": "apps/v1",
    "kind": "Deployment",
    "metadata": {
      "name": "my-app"
    },
    "spec": {
      "replicas": 1,
      "selector": {
        "matchLabels": {
          "app": "my-app"
        }
      },
      "template": {
        "metadata": {
          "labels": {
            "app": "my-app"
          }
        },
        "spec": {
          "containers": [
            {
              "name": "app",
              "image": "nginx:latest"
            }
          ]
        }
      }
    }
  }
}

Get a specific workload.

get

Retrieve details of a specific workload by ID

Authorizations

AuthorizationstringRequired

Bearer authentication

Path parameters

WorkloadV2Idstring · uuidRequired

The ID of the workload.

Responses

200

Successfully retrieved the workload

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

The specified resource was not found

application/json

500

unexpected error

application/json

503

unexpected error

application/json

get/api/v2/workloads/{WorkloadV2Id}

GET /api/v2/workloads/{WorkloadV2Id} HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "workload": {
    "metadata": {
      "name": "my-workload-name",
      "projectId": 1,
      "priority": "text",
      "category": "text",
      "preemptibility": "preemptible",
      "configuration": {
        "mnnvl": "text",
        "userCredentials": {
          "sources": [
            {
              "ref": "my-hf-token-abc1234567"
            }
          ]
        }
      },
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "gvk": {
        "group": "apps",
        "version": "v1",
        "kind": "Deployment"
      },
      "projectName": "project-a",
      "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
      "tenantId": 1001,
      "departmentId": 2,
      "departmentName": "default",
      "createdAt": "2024-01-15T10:30:00Z",
      "createdBy": "user@run.ai",
      "updatedAt": "2024-01-15T10:35:00Z",
      "updatedBy": "user@run.ai",
      "deletedAt": "2024-01-15T10:35:00Z",
      "deletedBy": "user@run.ai"
    },
    "desiredPhase": "Running",
    "workloadManifest": {
      "apiVersion": "apps/v1",
      "kind": "Deployment",
      "metadata": {
        "name": "my-app"
      },
      "spec": {
        "replicas": 1,
        "selector": {
          "matchLabels": {
            "app": "my-app"
          }
        },
        "template": {
          "metadata": {
            "labels": {
              "app": "my-app"
            }
          },
          "spec": {
            "containers": [
              {
                "name": "app",
                "image": "nginx:latest"
              }
            ]
          }
        }
      }
    },
    "rawManifest": {
      "apiVersion": "apps/v1",
      "kind": "Deployment",
      "metadata": {
        "name": "my-app"
      },
      "spec": {
        "replicas": 1,
        "selector": {
          "matchLabels": {
            "app": "my-app"
          }
        },
        "template": {
          "metadata": {
            "labels": {
              "app": "my-app"
            }
          },
          "spec": {
            "containers": [
              {
                "name": "app",
                "image": "nginx:latest"
              }
            ]
          }
        }
      }
    }
  },
  "syncInfo": {
    "status": "Queued",
    "message": "text"
  }
}

Update workload spec.

put

Update the specification of an existing workload.

Authorizations

AuthorizationstringRequired

Bearer authentication

Path parameters

WorkloadV2Idstring · uuidRequired

The ID of the workload.

Body

manifestBase64Encodedstring · byte · max: 2097152Optional

Kubernetes YAML manifest encoded in base 64. Mutually exclusive with manifest.

Example:

YXBpVmVyc2lvbjogdjEKa2luZDogUG9kCm1ldGFkYXRhOgogIG5hbWU6IG15LXBvZApzcGVjOgogIGNvbnRhaW5lcnM6CiAgLSBuYW1lOiBuZ2lueAogICAgaW1hZ2U6IG5naW54OmxhdGVzdAo=

Responses

202

Workload update request accepted

application/json

desiredPhasestring · enumRequired

The desired phase of the workload.

Possible values:

401

Unauthorized

application/json

403

Forbidden

application/json

404

The specified resource was not found

application/json

500

unexpected error

application/json

503

unexpected error

application/json

put/api/v2/workloads/{WorkloadV2Id}

PUT /api/v2/workloads/{WorkloadV2Id} HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 490

{
  "metadata": {
    "priority": "text",
    "category": "text"
  },
  "manifest": {
    "apiVersion": "apps/v1",
    "kind": "Deployment",
    "metadata": {
      "name": "my-app"
    },
    "spec": {
      "replicas": 1,
      "selector": {
        "matchLabels": {
          "app": "my-app"
        }
      },
      "template": {
        "metadata": {
          "labels": {
            "app": "my-app"
          }
        },
        "spec": {
          "containers": [
            {
              "name": "app",
              "image": "nginx:latest"
            }
          ]
        }
      }
    }
  },
  "manifestBase64Encoded": "YXBpVmVyc2lvbjogdjEKa2luZDogUG9kCm1ldGFkYXRhOgogIG5hbWU6IG15LXBvZApzcGVjOgogIGNvbnRhaW5lcnM6CiAgLSBuYW1lOiBuZ2lueAogICAgaW1hZ2U6IG5naW54OmxhdGVzdAo="
}

{
  "metadata": {
    "name": "my-workload-name",
    "projectId": 1,
    "priority": "text",
    "category": "text",
    "preemptibility": "preemptible",
    "configuration": {
      "mnnvl": "text",
      "userCredentials": {
        "sources": [
          {
            "ref": "my-hf-token-abc1234567"
          }
        ]
      }
    },
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "gvk": {
      "group": "apps",
      "version": "v1",
      "kind": "Deployment"
    },
    "projectName": "project-a",
    "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
    "tenantId": 1001,
    "departmentId": 2,
    "departmentName": "default",
    "createdAt": "2024-01-15T10:30:00Z",
    "createdBy": "user@run.ai",
    "updatedAt": "2024-01-15T10:35:00Z",
    "updatedBy": "user@run.ai",
    "deletedAt": "2024-01-15T10:35:00Z",
    "deletedBy": "user@run.ai"
  },
  "desiredPhase": "Running",
  "workloadManifest": {
    "apiVersion": "apps/v1",
    "kind": "Deployment",
    "metadata": {
      "name": "my-app"
    },
    "spec": {
      "replicas": 1,
      "selector": {
        "matchLabels": {
          "app": "my-app"
        }
      },
      "template": {
        "metadata": {
          "labels": {
            "app": "my-app"
          }
        },
        "spec": {
          "containers": [
            {
              "name": "app",
              "image": "nginx:latest"
            }
          ]
        }
      }
    }
  },
  "rawManifest": {
    "apiVersion": "apps/v1",
    "kind": "Deployment",
    "metadata": {
      "name": "my-app"
    },
    "spec": {
      "replicas": 1,
      "selector": {
        "matchLabels": {
          "app": "my-app"
        }
      },
      "template": {
        "metadata": {
          "labels": {
            "app": "my-app"
          }
        },
        "spec": {
          "containers": [
            {
              "name": "app",
              "image": "nginx:latest"
            }
          ]
        }
      }
    }
  }
}

Delete a workload.

delete

Delete a specific workload by ID

Authorizations

AuthorizationstringRequired

Bearer authentication

Path parameters

WorkloadV2Idstring · uuidRequired

The ID of the workload.

Responses

202

Deletion request accepted.

application/json

desiredPhasestring · enumRequired

The desired phase of the workload.

Possible values:

401

Unauthorized

application/json

403

Forbidden

application/json

404

The specified resource was not found

application/json

500

unexpected error

application/json

503

unexpected error

application/json

delete/api/v2/workloads/{WorkloadV2Id}

DELETE /api/v2/workloads/{WorkloadV2Id} HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "metadata": {
    "name": "my-workload-name",
    "projectId": 1,
    "priority": "text",
    "category": "text",
    "preemptibility": "preemptible",
    "configuration": {
      "mnnvl": "text",
      "userCredentials": {
        "sources": [
          {
            "ref": "my-hf-token-abc1234567"
          }
        ]
      }
    },
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "gvk": {
      "group": "apps",
      "version": "v1",
      "kind": "Deployment"
    },
    "projectName": "project-a",
    "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
    "tenantId": 1001,
    "departmentId": 2,
    "departmentName": "default",
    "createdAt": "2024-01-15T10:30:00Z",
    "createdBy": "user@run.ai",
    "updatedAt": "2024-01-15T10:35:00Z",
    "updatedBy": "user@run.ai",
    "deletedAt": "2024-01-15T10:35:00Z",
    "deletedBy": "user@run.ai"
  },
  "desiredPhase": "Running",
  "workloadManifest": {
    "apiVersion": "apps/v1",
    "kind": "Deployment",
    "metadata": {
      "name": "my-app"
    },
    "spec": {
      "replicas": 1,
      "selector": {
        "matchLabels": {
          "app": "my-app"
        }
      },
      "template": {
        "metadata": {
          "labels": {
            "app": "my-app"
          }
        },
        "spec": {
          "containers": [
            {
              "name": "app",
              "image": "nginx:latest"
            }
          ]
        }
      }
    }
  },
  "rawManifest": {
    "apiVersion": "apps/v1",
    "kind": "Deployment",
    "metadata": {
      "name": "my-app"
    },
    "spec": {
      "replicas": 1,
      "selector": {
        "matchLabels": {
          "app": "my-app"
        }
      },
      "template": {
        "metadata": {
          "labels": {
            "app": "my-app"
          }
        },
        "spec": {
          "containers": [
            {
              "name": "app",
              "image": "nginx:latest"
            }
          ]
        }
      }
    }
  }
}

PreviousWorkloads NextNVIDIA NIM

Last updated 15 days ago