Ctrlk
Contact support
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Workload Properties

Workload properties define the behavioral and scheduling characteristics of a workload submitted to the NVIDIA Run:ai platform. These properties such as type, category, and priority determine how workloads are classified, monitored, and scheduled.

  • Type - Defines the functional behavior of a workload, such as training or inference, and serves as the foundation for how it is classified within the platform. Each workload type includes a default category (used for monitoring) and a default priority (used for scheduling within a project).

  • Category - Represents the role or purpose of a workload, such as Build, Train, Deploy. Each workload type is assigned a default category to ensure consistent classification across the platform for monitoring purposes. See Monitor workloads by category.

  • Priority - Determines the scheduling order of workloads within a project and whether a workload can be preempted. Higher-priority workloads are scheduled first and may become non-preemptible, preventing interruption by lower-priority workloads. See Workload priority control.

List workload categories.

get

Retrieves a list of workload categories. These categories are used to classify and monitor different types of workloads within the NVIDIA Run:ai platform.

Authorizations
AuthorizationstringRequired

Bearer authentication

Responses
200

List of categories retrieved successfully.

application/json
get/api/v1/workload-categories
GET /api/v1/workload-categories HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "categories": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "description": "text",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "createdBy": "text"
    }
  ]
}

Get workload category by id.

get

Retrieves a specific workload category by its ID. Workload categories are used to classify and monitor different types of workloads within the NVIDIA Run:ai platform.

Authorizations
AuthorizationstringRequired

Bearer authentication

Path parameters
categoryIdstring · uuidRequired

The unique identifier of the workload category.

Responses
200

Category retrieved successfully

application/json
idstring · uuidRequired

The unique identifier of the workload category.

namestringRequired

A unique, human-readable name for the workload category.

descriptionstringOptional

An optional description providing additional details about the category.

createdAtstring · date-timeOptional

The date and time when the workload category was created.

createdBystringOptional

The user who created the workload category.

get/api/v1/workload-categories/{categoryId}
GET /api/v1/workload-categories/{categoryId} HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "createdBy": "text"
}

List workload types.

get

Retrieves a list of workload types with their configurations - their corresponding workload categories and priorities.

Authorizations
AuthorizationstringRequired

Bearer authentication

Query parameters
externalTypesOnlybooleanOptional

Return only external and user_external sourced workload types.

Default: false
filterBystring[] · max: 10Optional

Filter results by a parameter. Use the format field-name operator value. Operators are == Equals, != Not equals, <= Less than or equal, >= Greater than or equal, =@ contains, !@ Does not contain, =^ Starts with and =$ Ends with. Dates are in ISO 8601 timestamp format and available for operators ==, !=, <= and >=.

Example: ["name==Deployment","group==apps"]
Responses
200

List of types retrieved successfully

application/json
get/api/v1/workload-types
GET /api/v1/workload-types HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "types": [
    {
      "categoryId": "123e4567-e89b-12d3-a456-426614174000",
      "priorityId": "123e4567-e89b-12d3-a456-426614174000",
      "preemptibility": "non-preemptible",
      "name": "Deployment",
      "group": "apps",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "categoryName": "Build",
      "priorityName": "medium",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "updatedBy": "text",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "createdBy": "text",
      "kartas": [
        {
          "version": "v1",
          "karta": {
            "spec": {
              "structureDefinition": {
                "rootComponent": {
                  "kind": {
                    "group": "apps",
                    "version": "v1",
                    "kind": "Deployment"
                  }
                }
              }
            }
          }
        }
      ],
      "clusterStatuses": [
        {
          "phase": "Ready",
          "conditions": [
            {
              "type": "Ready",
              "status": "False",
              "message": "Resource validation failed: ...",
              "reason": "ErrorConfig",
              "lastTransitionTime": "2022-01-01T03:49:52.531Z"
            }
          ],
          "version": "v1",
          "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
          "updatedAt": "2026-01-01T00:00:00.000Z"
        }
      ]
    }
  ]
}

Create a workload type. [Experimental]

post

Create a new workload type in the system by providing its identification details and configuration, making it available for use and management within the platform.

Authorizations
AuthorizationstringRequired

Bearer authentication

Body
categoryIdstring · uuidRequired

The unique identifier of the workload category.

priorityIdstring · uuidRequired

The unique identifier of the workload priority.

preemptibilitystring · enumOptional

Indicates the default preemptibility level of the workload type. Only available for workloads submitted to clusters of versions 2.24+. The default, if not specified, is if priority.value >= 100 - then 'non-preemptible', else 'preemptible'.

Example: non-preemptiblePossible values:
namestringRequired

The unique name of the workload type. This value must exactly match the Kubernetes Kind that represents the workload type.

Example: DeploymentPattern: ^[A-Z][a-z0-9]*([A-Z][a-z0-9]*)*$
groupstringRequired

The Kubernetes group associated with the workload resource.

Example: appsPattern: ^[a-z](?:[a-z0-9.-]*[a-z0-9])?$
Responses
201

Created

application/json
categoryIdstring · uuidRequired

The unique identifier of the workload category.

priorityIdstring · uuidRequired

The unique identifier of the workload priority.

preemptibilitystring · enumRequired

Indicates the default preemptibility level of the workload type. Only available for workloads submitted to clusters of versions 2.24+. The default, if not specified, is if priority.value >= 100 - then 'non-preemptible', else 'preemptible'.

Example: non-preemptiblePossible values:
namestringRequired

The unique name of the workload type. This value must exactly match the Kubernetes Kind that represents the workload type.

Example: DeploymentPattern: ^[A-Z][a-z0-9]*([A-Z][a-z0-9]*)*$
groupstringRequired

The Kubernetes group associated with the workload resource.

Example: appsPattern: ^[a-z](?:[a-z0-9.-]*[a-z0-9])?$
idstring · uuidOptional

The unique identifier of the workload type.

categoryNamestringOptional

The name of the workload category.

Example: Build
priorityNamestringOptional

The name of the workload priority.

Example: medium
updatedAtstring · date-timeOptional

The timestamp for the last time the workload type was updated.

updatedBystringOptional

Identifier of the user who last updated the workload type.

createdAtstring · date-timeOptional

The timestamp for when the workload type was created.

createdBystringOptional

Identifier of the user who created the workload type.

post/api/v1/workload-types
POST /api/v1/workload-types HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 287

{
  "categoryId": "123e4567-e89b-12d3-a456-426614174000",
  "priorityId": "123e4567-e89b-12d3-a456-426614174000",
  "preemptibility": "text",
  "name": "Deployment",
  "group": "apps",
  "kartas": [
    {
      "spec": {
        "structureDefinition": {
          "rootComponent": {
            "kind": {
              "group": "apps",
              "version": "v1",
              "kind": "Deployment"
            }
          }
        }
      }
    }
  ]
}
{
  "categoryId": "123e4567-e89b-12d3-a456-426614174000",
  "priorityId": "123e4567-e89b-12d3-a456-426614174000",
  "preemptibility": "non-preemptible",
  "name": "Deployment",
  "group": "apps",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "categoryName": "Build",
  "priorityName": "medium",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "updatedBy": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "createdBy": "text",
  "kartas": [
    {
      "version": "v1",
      "karta": {
        "spec": {
          "structureDefinition": {
            "rootComponent": {
              "kind": {
                "group": "apps",
                "version": "v1",
                "kind": "Deployment"
              }
            }
          }
        }
      }
    }
  ],
  "clusterStatuses": [
    {
      "phase": "Ready",
      "conditions": [
        {
          "type": "Ready",
          "status": "False",
          "message": "Resource validation failed: ...",
          "reason": "ErrorConfig",
          "lastTransitionTime": "2022-01-01T03:49:52.531Z"
        }
      ],
      "version": "v1",
      "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

List workload type by id.

get

Retrieves a specific workload type by its ID.

Authorizations
AuthorizationstringRequired

Bearer authentication

Path parameters
workloadTypeIdstring · uuidRequired

The unique identifier of the workload type.

Responses
200

Type retrieved successfully

application/json
categoryIdstring · uuidRequired

The unique identifier of the workload category.

priorityIdstring · uuidRequired

The unique identifier of the workload priority.

preemptibilitystring · enumRequired

Indicates the default preemptibility level of the workload type. Only available for workloads submitted to clusters of versions 2.24+. The default, if not specified, is if priority.value >= 100 - then 'non-preemptible', else 'preemptible'.

Example: non-preemptiblePossible values:
namestringRequired

The unique name of the workload type. This value must exactly match the Kubernetes Kind that represents the workload type.

Example: DeploymentPattern: ^[A-Z][a-z0-9]*([A-Z][a-z0-9]*)*$
groupstringRequired

The Kubernetes group associated with the workload resource.

Example: appsPattern: ^[a-z](?:[a-z0-9.-]*[a-z0-9])?$
idstring · uuidOptional

The unique identifier of the workload type.

categoryNamestringOptional

The name of the workload category.

Example: Build
priorityNamestringOptional

The name of the workload priority.

Example: medium
updatedAtstring · date-timeOptional

The timestamp for the last time the workload type was updated.

updatedBystringOptional

Identifier of the user who last updated the workload type.

createdAtstring · date-timeOptional

The timestamp for when the workload type was created.

createdBystringOptional

Identifier of the user who created the workload type.

get/api/v1/workload-types/{workloadTypeId}
GET /api/v1/workload-types/{workloadTypeId} HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "categoryId": "123e4567-e89b-12d3-a456-426614174000",
  "priorityId": "123e4567-e89b-12d3-a456-426614174000",
  "preemptibility": "non-preemptible",
  "name": "Deployment",
  "group": "apps",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "categoryName": "Build",
  "priorityName": "medium",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "updatedBy": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "createdBy": "text",
  "kartas": [
    {
      "version": "v1",
      "karta": {
        "spec": {
          "structureDefinition": {
            "rootComponent": {
              "kind": {
                "group": "apps",
                "version": "v1",
                "kind": "Deployment"
              }
            }
          }
        }
      }
    }
  ],
  "clusterStatuses": [
    {
      "phase": "Ready",
      "conditions": [
        {
          "type": "Ready",
          "status": "False",
          "message": "Resource validation failed: ...",
          "reason": "ErrorConfig",
          "lastTransitionTime": "2022-01-01T03:49:52.531Z"
        }
      ],
      "version": "v1",
      "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Update a workload type by id.

put

Update the default category or priority assigned to a workload type.

Authorizations
AuthorizationstringRequired

Bearer authentication

Path parameters
workloadTypeIdstring · uuidRequired

The unique identifier of the workload type.

Body
categoryIdstring · uuidOptional

The unique identifier of the workload category.

priorityIdstring · uuidOptional

The unique identifier of the workload priority.

preemptibilitystring · enumOptional

Indicates the default preemptibility level of the workload type. Only available for workloads submitted to clusters of versions 2.24+. The default, if not specified, is if priority.value >= 100 - then 'non-preemptible', else 'preemptible'.

Example: non-preemptiblePossible values:
Responses
200

Updated successfully

application/json
categoryIdstring · uuidRequired

The unique identifier of the workload category.

priorityIdstring · uuidRequired

The unique identifier of the workload priority.

preemptibilitystring · enumRequired

Indicates the default preemptibility level of the workload type. Only available for workloads submitted to clusters of versions 2.24+. The default, if not specified, is if priority.value >= 100 - then 'non-preemptible', else 'preemptible'.

Example: non-preemptiblePossible values:
namestringRequired

The unique name of the workload type. This value must exactly match the Kubernetes Kind that represents the workload type.

Example: DeploymentPattern: ^[A-Z][a-z0-9]*([A-Z][a-z0-9]*)*$
groupstringRequired

The Kubernetes group associated with the workload resource.

Example: appsPattern: ^[a-z](?:[a-z0-9.-]*[a-z0-9])?$
idstring · uuidOptional

The unique identifier of the workload type.

categoryNamestringOptional

The name of the workload category.

Example: Build
priorityNamestringOptional

The name of the workload priority.

Example: medium
updatedAtstring · date-timeOptional

The timestamp for the last time the workload type was updated.

updatedBystringOptional

Identifier of the user who last updated the workload type.

createdAtstring · date-timeOptional

The timestamp for when the workload type was created.

createdBystringOptional

Identifier of the user who created the workload type.

put/api/v1/workload-types/{workloadTypeId}
PUT /api/v1/workload-types/{workloadTypeId} HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 252

{
  "categoryId": "123e4567-e89b-12d3-a456-426614174000",
  "priorityId": "123e4567-e89b-12d3-a456-426614174000",
  "preemptibility": "text",
  "kartas": [
    {
      "spec": {
        "structureDefinition": {
          "rootComponent": {
            "kind": {
              "group": "apps",
              "version": "v1",
              "kind": "Deployment"
            }
          }
        }
      }
    }
  ]
}
{
  "categoryId": "123e4567-e89b-12d3-a456-426614174000",
  "priorityId": "123e4567-e89b-12d3-a456-426614174000",
  "preemptibility": "non-preemptible",
  "name": "Deployment",
  "group": "apps",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "categoryName": "Build",
  "priorityName": "medium",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "updatedBy": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "createdBy": "text",
  "kartas": [
    {
      "version": "v1",
      "karta": {
        "spec": {
          "structureDefinition": {
            "rootComponent": {
              "kind": {
                "group": "apps",
                "version": "v1",
                "kind": "Deployment"
              }
            }
          }
        }
      }
    }
  ],
  "clusterStatuses": [
    {
      "phase": "Ready",
      "conditions": [
        {
          "type": "Ready",
          "status": "False",
          "message": "Resource validation failed: ...",
          "reason": "ErrorConfig",
          "lastTransitionTime": "2022-01-01T03:49:52.531Z"
        }
      ],
      "version": "v1",
      "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Delete a workload type by id. [Experimental]

delete

Deletes a specific workload type by its ID.

Authorizations
AuthorizationstringRequired

Bearer authentication

Path parameters
workloadTypeIdstring · uuidRequired

The unique identifier of the workload type.

Responses
204

No Content.

No content
delete/api/v1/workload-types/{workloadTypeId}
DELETE /api/v1/workload-types/{workloadTypeId} HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Get workload priorities.

get

Retrieve the list of all workload priorities available in the system

Authorizations
AuthorizationstringRequired

Bearer authentication

Query parameters
sortOrderstring · enumOptional

Sort results in descending or ascending order.

Default: ascPossible values:
sortBystring · enumOptional

Defines the field to sort the results by

Possible values:
filterBystring[] · max: 10Optional

Filter results by a parameter. Use the format field-name operator value. Operators are == Equals, != Not equals, <= Less than or equal, >= Greater than or equal, =@ contains, !@ Does not contains, =^ Starts with and =$ Ends with. Dates are in ISO 8601 timestamp format and available for operators ==, !=, <= and >=

Example: ["name!=some-name"]
Responses
200

Request completed successfully.

application/json
get/api/v1/workload-priorities
GET /api/v1/workload-priorities HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "priorities": [
    {
      "aggregatedPhase": "Ready",
      "status": [
        {
          "clusterId": "d73a738f-fab3-430a-8fa3-5241493d7128",
          "phase": "Ready"
        }
      ],
      "scopeType": "tenant",
      "scopeId": "1",
      "id": "d73a738f-fab3-430a-8fa3-5241493d7128",
      "source": "Run:ai",
      "name": "medium",
      "value": 50,
      "createdAt": "2022-01-01T03:49:52.531Z",
      "updatedAt": "2022-06-08T11:28:24.131Z"
    }
  ]
}
PreviousWorkloads BatchNextWorkload Templates

Last updated