# 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](https://run-ai-docs.nvidia.com/self-hosted/workloads-in-nvidia-run-ai/workload-types/extending-workload-support) for more details.

## Create a workload. \[Experimental]

> Submit a workload with metadata and a Kubernetes manifest.

```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.23"},"tags":[{"name":"Workloads V2","description":"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.\nEach submission combines the user’s Kubernetes manifest with NVIDIA Run:ai scheduling metadata, enabling consistent orchestration, monitoring, and governance. See [Extending workload support](https://run-ai-docs.nvidia.com/self-hosted/workloads-in-nvidia-run-ai/workload-types/extending-workload-support) for more details.\n"}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"schemas":{"WorkloadV2CreateRequest":{"type":"object","required":["metadata"],"properties":{"metadata":{"$ref":"#/components/schemas/WorkloadV2MetadataCreateParams"},"manifest":{"$ref":"#/components/schemas/Manifest"},"manifestBase64Encoded":{"$ref":"#/components/schemas/ManifestEncoded"}}},"WorkloadV2MetadataCreateParams":{"type":"object","required":["name","projectId"],"properties":{"name":{"$ref":"#/components/schemas/WorkloadName"},"projectId":{"$ref":"#/components/schemas/ProjectId"},"priority":{"$ref":"#/components/schemas/PriorityClass"},"category":{"$ref":"#/components/schemas/Category"}}},"WorkloadName":{"description":"The name of the workload.","type":"string","minLength":1,"pattern":".*"},"ProjectId":{"description":"The id of the project.","type":"string","pattern":".*"},"PriorityClass":{"description":"Specifies the priority class for the workload. Valid values are: very-low, low, medium-low, medium, medium-high, high, very-high. You can use this parameter to adjust the workload's scheduling behavior. Each workload type has a default priority. To view the default priority for each workload type, use the GET /workload-types endpoint.","type":"string","nullable":true,"pattern":".*"},"Category":{"description":"Specify the workload category assigned to the workload. Categories are used to classify and monitor different types of workloads within the NVIDIA Run:ai platform.","type":"string","nullable":true,"pattern":".*"},"Manifest":{"type":"object","description":"The full Kubernetes manifest for the workload in JSON form. Mutually exclusive with manifestEncodedBase64.","additionalProperties":true},"ManifestEncoded":{"type":"string","format":"byte","description":"Kubernetes YAML manifest encoded in base 64. Mutually exclusive with manifest."},"WorkloadV2":{"type":"object","required":["metadata","desiredPhase","workloadManifest","rawManifest"],"properties":{"metadata":{"$ref":"#/components/schemas/WorkloadV2Metadata"},"desiredPhase":{"$ref":"#/components/schemas/DesiredPhase"},"workloadManifest":{"$ref":"#/components/schemas/Manifest"},"rawManifest":{"$ref":"#/components/schemas/Manifest"}}},"WorkloadV2Metadata":{"allOf":[{"$ref":"#/components/schemas/WorkloadV2MetadataCreateParams"},{"$ref":"#/components/schemas/WorkloadV2MetadataAutoFill"}]},"WorkloadV2MetadataAutoFill":{"type":"object","required":["id","gvk","projectName","clusterId","tenantId","departmentId","departmentName","createdAt","createdBy","updatedAt","updatedBy"],"properties":{"id":{"$ref":"#/components/schemas/WorkloadId3"},"gvk":{"$ref":"#/components/schemas/GVK"},"projectName":{"$ref":"#/components/schemas/ProjectName2"},"clusterId":{"$ref":"#/components/schemas/ClusterId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"departmentId":{"$ref":"#/components/schemas/DepartmentId3"},"departmentName":{"$ref":"#/components/schemas/DepartmentName1"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp for when the workload was created."},"createdBy":{"type":"string","description":"Identifier of the user who created the workload.","format":".*"},"updatedAt":{"type":"string","format":"date-time","description":"The timestamp for the last time the workload was updated."},"updatedBy":{"type":"string","description":"Identifier of the user who last updated the workload.","format":".*"},"deletedAt":{"type":"string","format":"date-time","description":"The timestamp indicating when the workload was deleted.","nullable":true},"deletedBy":{"type":"string","format":".*","description":"Identifier of the user who deleted the workload.","nullable":true}}},"WorkloadId3":{"description":"A unique ID of the workload.","type":"string","format":"uuid"},"GVK":{"type":"object","description":"Specifies the Group, Version, and Kind (GVK) of the Kubernetes resource that defines the workload.","required":["group","version","kind"],"properties":{"group":{"description":"The API group of the Kubernetes resource.","type":"string"},"version":{"description":"The API version of the resource within the specified group.","type":"string"},"kind":{"description":"The type of Kubernetes resource being referenced.","type":"string"}}},"ProjectName2":{"type":"string","description":"The name of the project","minLength":1,"pattern":"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$"},"ClusterId":{"description":"The id of the cluster.","type":"string","format":"uuid"},"TenantId":{"description":"The id of the tenant.","type":"integer","format":"int32"},"DepartmentId3":{"description":"The id of the department.","type":"string","minLength":1,"pattern":".*"},"DepartmentName1":{"type":"string","description":"The name of the department","minLength":1,"pattern":"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$"},"DesiredPhase":{"description":"The desired phase of the workload.","type":"string","enum":["Running","Stopped","Deleted"]},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"400BadRequest":{"description":"Bad request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409Conflict":{"description":"The specified resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v2/workloads":{"post":{"summary":"Create a workload. [Experimental]","description":"Submit a workload with metadata and a Kubernetes manifest.","operationId":"create_workload_v2","tags":["Workloads V2"],"requestBody":{"description":"Workload metadata and manifest","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkloadV2CreateRequest"}}}},"responses":{"202":{"description":"Workload creation request accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkloadV2"}}}},"400":{"$ref":"#/components/responses/400BadRequest"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"409":{"$ref":"#/components/responses/409Conflict"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```

## Get a specific workload. \[Experimental]

> Retrieve details of a specific workload by ID

```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.23"},"tags":[{"name":"Workloads V2","description":"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.\nEach submission combines the user’s Kubernetes manifest with NVIDIA Run:ai scheduling metadata, enabling consistent orchestration, monitoring, and governance. See [Extending workload support](https://run-ai-docs.nvidia.com/self-hosted/workloads-in-nvidia-run-ai/workload-types/extending-workload-support) for more details.\n"}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"WorkloadV2Id":{"name":"WorkloadV2Id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The ID of the workload."}}},"schemas":{"WorkloadV2GetResponse":{"type":"object","required":["workload"],"properties":{"workload":{"$ref":"#/components/schemas/WorkloadV2"},"syncInfo":{"$ref":"#/components/schemas/WorkloadV2SyncInfo"}}},"WorkloadV2":{"type":"object","required":["metadata","desiredPhase","workloadManifest","rawManifest"],"properties":{"metadata":{"$ref":"#/components/schemas/WorkloadV2Metadata"},"desiredPhase":{"$ref":"#/components/schemas/DesiredPhase"},"workloadManifest":{"$ref":"#/components/schemas/Manifest"},"rawManifest":{"$ref":"#/components/schemas/Manifest"}}},"WorkloadV2Metadata":{"allOf":[{"$ref":"#/components/schemas/WorkloadV2MetadataCreateParams"},{"$ref":"#/components/schemas/WorkloadV2MetadataAutoFill"}]},"WorkloadV2MetadataCreateParams":{"type":"object","required":["name","projectId"],"properties":{"name":{"$ref":"#/components/schemas/WorkloadName"},"projectId":{"$ref":"#/components/schemas/ProjectId"},"priority":{"$ref":"#/components/schemas/PriorityClass"},"category":{"$ref":"#/components/schemas/Category"}}},"WorkloadName":{"description":"The name of the workload.","type":"string","minLength":1,"pattern":".*"},"ProjectId":{"description":"The id of the project.","type":"string","pattern":".*"},"PriorityClass":{"description":"Specifies the priority class for the workload. Valid values are: very-low, low, medium-low, medium, medium-high, high, very-high. You can use this parameter to adjust the workload's scheduling behavior. Each workload type has a default priority. To view the default priority for each workload type, use the GET /workload-types endpoint.","type":"string","nullable":true,"pattern":".*"},"Category":{"description":"Specify the workload category assigned to the workload. Categories are used to classify and monitor different types of workloads within the NVIDIA Run:ai platform.","type":"string","nullable":true,"pattern":".*"},"WorkloadV2MetadataAutoFill":{"type":"object","required":["id","gvk","projectName","clusterId","tenantId","departmentId","departmentName","createdAt","createdBy","updatedAt","updatedBy"],"properties":{"id":{"$ref":"#/components/schemas/WorkloadId3"},"gvk":{"$ref":"#/components/schemas/GVK"},"projectName":{"$ref":"#/components/schemas/ProjectName2"},"clusterId":{"$ref":"#/components/schemas/ClusterId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"departmentId":{"$ref":"#/components/schemas/DepartmentId3"},"departmentName":{"$ref":"#/components/schemas/DepartmentName1"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp for when the workload was created."},"createdBy":{"type":"string","description":"Identifier of the user who created the workload.","format":".*"},"updatedAt":{"type":"string","format":"date-time","description":"The timestamp for the last time the workload was updated."},"updatedBy":{"type":"string","description":"Identifier of the user who last updated the workload.","format":".*"},"deletedAt":{"type":"string","format":"date-time","description":"The timestamp indicating when the workload was deleted.","nullable":true},"deletedBy":{"type":"string","format":".*","description":"Identifier of the user who deleted the workload.","nullable":true}}},"WorkloadId3":{"description":"A unique ID of the workload.","type":"string","format":"uuid"},"GVK":{"type":"object","description":"Specifies the Group, Version, and Kind (GVK) of the Kubernetes resource that defines the workload.","required":["group","version","kind"],"properties":{"group":{"description":"The API group of the Kubernetes resource.","type":"string"},"version":{"description":"The API version of the resource within the specified group.","type":"string"},"kind":{"description":"The type of Kubernetes resource being referenced.","type":"string"}}},"ProjectName2":{"type":"string","description":"The name of the project","minLength":1,"pattern":"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$"},"ClusterId":{"description":"The id of the cluster.","type":"string","format":"uuid"},"TenantId":{"description":"The id of the tenant.","type":"integer","format":"int32"},"DepartmentId3":{"description":"The id of the department.","type":"string","minLength":1,"pattern":".*"},"DepartmentName1":{"type":"string","description":"The name of the department","minLength":1,"pattern":"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$"},"DesiredPhase":{"description":"The desired phase of the workload.","type":"string","enum":["Running","Stopped","Deleted"]},"Manifest":{"type":"object","description":"The full Kubernetes manifest for the workload in JSON form. Mutually exclusive with manifestEncodedBase64.","additionalProperties":true},"WorkloadV2SyncInfo":{"type":"object","required":["status"],"properties":{"status":{"$ref":"#/components/schemas/WorkloadV2SyncStatus"},"message":{"type":"string","pattern":".*"}}},"WorkloadV2SyncStatus":{"type":"string","enum":["Queued","Applying","Deleting","Synced","Deleted","Failed"]},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v2/workloads/{WorkloadV2Id}":{"get":{"summary":"Get a specific workload. [Experimental]","description":"Retrieve details of a specific workload by ID","operationId":"get_workload_v2_by_id","tags":["Workloads V2"],"parameters":[{"$ref":"#/components/parameters/WorkloadV2Id"}],"responses":{"200":{"description":"Successfully retrieved the workload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkloadV2GetResponse"}}}},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```

## Delete a workload. \[Experimental]

> Delete a specific workload by ID

```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.23"},"tags":[{"name":"Workloads V2","description":"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.\nEach submission combines the user’s Kubernetes manifest with NVIDIA Run:ai scheduling metadata, enabling consistent orchestration, monitoring, and governance. See [Extending workload support](https://run-ai-docs.nvidia.com/self-hosted/workloads-in-nvidia-run-ai/workload-types/extending-workload-support) for more details.\n"}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"WorkloadV2Id":{"name":"WorkloadV2Id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The ID of the workload."}}},"schemas":{"WorkloadV2":{"type":"object","required":["metadata","desiredPhase","workloadManifest","rawManifest"],"properties":{"metadata":{"$ref":"#/components/schemas/WorkloadV2Metadata"},"desiredPhase":{"$ref":"#/components/schemas/DesiredPhase"},"workloadManifest":{"$ref":"#/components/schemas/Manifest"},"rawManifest":{"$ref":"#/components/schemas/Manifest"}}},"WorkloadV2Metadata":{"allOf":[{"$ref":"#/components/schemas/WorkloadV2MetadataCreateParams"},{"$ref":"#/components/schemas/WorkloadV2MetadataAutoFill"}]},"WorkloadV2MetadataCreateParams":{"type":"object","required":["name","projectId"],"properties":{"name":{"$ref":"#/components/schemas/WorkloadName"},"projectId":{"$ref":"#/components/schemas/ProjectId"},"priority":{"$ref":"#/components/schemas/PriorityClass"},"category":{"$ref":"#/components/schemas/Category"}}},"WorkloadName":{"description":"The name of the workload.","type":"string","minLength":1,"pattern":".*"},"ProjectId":{"description":"The id of the project.","type":"string","pattern":".*"},"PriorityClass":{"description":"Specifies the priority class for the workload. Valid values are: very-low, low, medium-low, medium, medium-high, high, very-high. You can use this parameter to adjust the workload's scheduling behavior. Each workload type has a default priority. To view the default priority for each workload type, use the GET /workload-types endpoint.","type":"string","nullable":true,"pattern":".*"},"Category":{"description":"Specify the workload category assigned to the workload. Categories are used to classify and monitor different types of workloads within the NVIDIA Run:ai platform.","type":"string","nullable":true,"pattern":".*"},"WorkloadV2MetadataAutoFill":{"type":"object","required":["id","gvk","projectName","clusterId","tenantId","departmentId","departmentName","createdAt","createdBy","updatedAt","updatedBy"],"properties":{"id":{"$ref":"#/components/schemas/WorkloadId3"},"gvk":{"$ref":"#/components/schemas/GVK"},"projectName":{"$ref":"#/components/schemas/ProjectName2"},"clusterId":{"$ref":"#/components/schemas/ClusterId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"departmentId":{"$ref":"#/components/schemas/DepartmentId3"},"departmentName":{"$ref":"#/components/schemas/DepartmentName1"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp for when the workload was created."},"createdBy":{"type":"string","description":"Identifier of the user who created the workload.","format":".*"},"updatedAt":{"type":"string","format":"date-time","description":"The timestamp for the last time the workload was updated."},"updatedBy":{"type":"string","description":"Identifier of the user who last updated the workload.","format":".*"},"deletedAt":{"type":"string","format":"date-time","description":"The timestamp indicating when the workload was deleted.","nullable":true},"deletedBy":{"type":"string","format":".*","description":"Identifier of the user who deleted the workload.","nullable":true}}},"WorkloadId3":{"description":"A unique ID of the workload.","type":"string","format":"uuid"},"GVK":{"type":"object","description":"Specifies the Group, Version, and Kind (GVK) of the Kubernetes resource that defines the workload.","required":["group","version","kind"],"properties":{"group":{"description":"The API group of the Kubernetes resource.","type":"string"},"version":{"description":"The API version of the resource within the specified group.","type":"string"},"kind":{"description":"The type of Kubernetes resource being referenced.","type":"string"}}},"ProjectName2":{"type":"string","description":"The name of the project","minLength":1,"pattern":"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$"},"ClusterId":{"description":"The id of the cluster.","type":"string","format":"uuid"},"TenantId":{"description":"The id of the tenant.","type":"integer","format":"int32"},"DepartmentId3":{"description":"The id of the department.","type":"string","minLength":1,"pattern":".*"},"DepartmentName1":{"type":"string","description":"The name of the department","minLength":1,"pattern":"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$"},"DesiredPhase":{"description":"The desired phase of the workload.","type":"string","enum":["Running","Stopped","Deleted"]},"Manifest":{"type":"object","description":"The full Kubernetes manifest for the workload in JSON form. Mutually exclusive with manifestEncodedBase64.","additionalProperties":true},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v2/workloads/{WorkloadV2Id}":{"delete":{"summary":"Delete a workload. [Experimental]","description":"Delete a specific workload by ID","operationId":"delete_workload_v2","tags":["Workloads V2"],"parameters":[{"$ref":"#/components/parameters/WorkloadV2Id"}],"responses":{"202":{"description":"Deletion request accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkloadV2"}}}},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://run-ai-docs.nvidia.com/api/2.23/workloads/workloads-v2.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.