NVIDIA Run:ai

Departments

Departments, in the hierarchy of resource allocation, are above Projects. A Department can contain multiple Projects, and has its own quotas. A Department's quota supersedes the total of the Project quotas in the Department, so tt is recommended that a Department's quota be the total, or more than of all the Project quotas in the Department. For further information see, Working with Departments.

Create department

Create Department

SecuritybearerAuth
Request
Request Body schema: application/json
required

Department to create.

description
string

The description of the department.

object or null (SchedulingRules)

Scheduling rules that define time limits and idle GPU timeouts for workloads in this org-unit. These rules help manage resource utilization by automatically terminating or preempting idle or long-running workloads.

defaultNodePools
Array of strings or null

An ordered list of node pools that defines the default scheduling preference for workloads in this department. The Scheduler will attempt to schedule workloads on node pools in this order. This setting is enforced if no node pool list is defined in the workload policy.

object (NodeTypesPerWorkload)

Node type configurations for different workload types (training, workspace). Specifies which node types are allowed for each workload type. Enforced when no node type is configured in the workload policy.

name
required
string

The unique name of the department within the cluster. Must be a valid Kubernetes name (lowercase, alphanumeric, hyphens allowed).

clusterId
required
string <uuid> (ClusterId)

The id of the cluster.

object (OvertimeData)
required
Array of objects (ResourcesNullable)

An array of resource configurations for the department. Each entry defines GPU, CPU, and CPU memory assigned to a specific node pool.

Responses
201

Created

400

Bad request.

401

Unauthorized

403

Forbidden

409

The specified resource already exists

503

unexpected error

post/api/v1/org-unit/departments
Request samples
application/json
{
  • "description": "string",
  • "schedulingRules": {
    },
  • "defaultNodePools": [
    ],
  • "nodeTypes": {
    },
  • "name": "organization1",
  • "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
  • "overtimeData": {
    },
  • "resources": [
    ]
}
Response samples
application/json
{
  • "description": "string",
  • "schedulingRules": {
    },
  • "defaultNodePools": [
    ],
  • "nodeTypes": {
    },
  • "name": "organization1",
  • "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
  • "overtimeData": {
    },
  • "id": 50,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "updatedBy": "string",
  • "children": [
    ],
  • "projectsAggregatedResources": [
    ],
  • "status": {
    },
  • "totalResources": {
    },
  • "resources": [
    ]
}

Get departments

list departments

SecuritybearerAuth
Request
query Parameters
filterBy
Array of strings

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: filterBy=name!=some-name
sortBy
string (DepartmentFilterSortFields)

Sort results by a parameters.

Enum: "name" "clusterId" "totalGpuQuota" "gpuAllocated" "createdAt" "avgGpuAllocation24h" "avgGpuUtilization24h" "avgGpuMemoryUtilization24h" "avgGpuAllocation7d" "avgGpuUtilization7d" "avgGpuMemoryUtilization7d" "avgGpuAllocation30d" "avgGpuUtilization30d" "avgGpuMemoryUtilization30d"
verbosity
string (Verbosity)

Departments verbosity. If it is set to "verbose", status will be returned. If it is not defined or set to "brief" only unit specific data will be returned.

Enum: "meta" "brief" "verbose"
Example: verbosity=verbose
sortOrder
string
Default: "asc"

Sort results in descending or ascending order.

Enum: "asc" "desc"
offset
integer <int32>

The offset of the first item returned in the collection.

Example: offset=100
limit
integer <int32> [ 1 .. 500 ]
Default: 50

The maximum number of entries to return.

Responses
200

ok

400

Bad request.

401

Unauthorized

403

Forbidden

503

unexpected error

get/api/v1/org-unit/departments
Response samples
application/json
{
  • "departments": [
    ],
  • "next": 1
}

Update department

Update department by Id

SecuritybearerAuth
Request
path Parameters
departmentId
required
string.*

The id of the department.

Example: 1
Request Body schema: application/json
required

Department to update.

description
string

The description of the department.

object or null (SchedulingRules)

Scheduling rules that define time limits and idle GPU timeouts for workloads in this org-unit. These rules help manage resource utilization by automatically terminating or preempting idle or long-running workloads.

defaultNodePools
Array of strings or null

An ordered list of node pools that defines the default scheduling preference for workloads in this department. The Scheduler will attempt to schedule workloads on node pools in this order. This setting is enforced if no node pool list is defined in the workload policy.

object (NodeTypesPerWorkload)

Node type configurations for different workload types (training, workspace). Specifies which node types are allowed for each workload type. Enforced when no node type is configured in the workload policy.

required
Array of objects (ResourcesNullable)

Resources assigned to this Organization per Node Pool

Responses
200

Updated

400

Bad request.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

503

unexpected error

put/api/v1/org-unit/departments/{departmentId}
Request samples
application/json
{
  • "description": "string",
  • "schedulingRules": {
    },
  • "defaultNodePools": [
    ],
  • "nodeTypes": {
    },
  • "resources": [
    ]
}
Response samples
application/json
{
  • "description": "string",
  • "schedulingRules": {
    },
  • "defaultNodePools": [
    ],
  • "nodeTypes": {
    },
  • "name": "organization1",
  • "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
  • "overtimeData": {
    },
  • "id": 50,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "updatedBy": "string",
  • "children": [
    ],
  • "projectsAggregatedResources": [
    ],
  • "status": {
    },
  • "totalResources": {
    },
  • "resources": [
    ]
}

Get department

Get department by Id

SecuritybearerAuth
Request
path Parameters
departmentId
required
string.*

The id of the department.

Example: 1
Responses
200

ok

401

Unauthorized

403

Forbidden

404

The specified resource was not found

503

unexpected error

get/api/v1/org-unit/departments/{departmentId}
Response samples
application/json
{
  • "description": "string",
  • "schedulingRules": {
    },
  • "defaultNodePools": [
    ],
  • "nodeTypes": {
    },
  • "name": "organization1",
  • "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
  • "overtimeData": {
    },
  • "id": 50,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "updatedBy": "string",
  • "children": [
    ],
  • "projectsAggregatedResources": [
    ],
  • "status": {
    },
  • "totalResources": {
    },
  • "resources": [
    ]
}

Delete department

Delete department by Id

SecuritybearerAuth
Request
path Parameters
departmentId
required
string.*

The id of the department.

Example: 1
Responses
204

Deleted

400

Bad request.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

503

unexpected error

delete/api/v1/org-unit/departments/{departmentId}
Response samples
application/json
{
  • "code": 400,
  • "message": "Required parameter is missing"
}

Update department resources

Update department resources by Id

SecuritybearerAuth
Request
path Parameters
departmentId
required
string.*

The id of the department.

Example: 1
Request Body schema: application/json
required

Department resources to update.

Array
object or null

The node pool to which this resource configuration applies.

object

Defines the GPU quota assignment, maximum GPU device allocation, and weight assigned that determines the fairshare of over-quota resources.

object or null

Defines the CPU quota assignment in millicores (1000 millicores = 1 CPU core), maximum CPU allocation, and weight.

object or null

Defines the CPU memory quota assignment, maximum allocation, and weight.

rank
string or null
Default: "MediumLow"

The scheduling rank of this org-unit within the node pool. Determines the scheduling order of workloads between org-units. Workloads in higher-ranked org-units are scheduled before workloads in lower-ranked org-units. For example, all workloads in rank "High" will be scheduled before all workloads in rank "Medium".

priority
string or null
Deprecated

Deprecated. Use rank instead. The scheduling priority for workloads in this node pool.

Responses
200

Updated

400

Bad request.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

put/api/v1/org-unit/departments/{departmentId}/resources
Request samples
application/json
[
  • {
    }
]
Response samples
application/json
[
  • {
    }
]

Patch department resources

Partial updates to specific items in the list. Should be used for update one or more attributes of an item without modifying the entire resource.

SecuritybearerAuth
Request
path Parameters
departmentId
required
string.*

The id of the department.

Example: 1
Request Body schema: application/json
required

Department resources to update.

Array
object or null

The node pool to which this resource configuration applies.

object

Defines the GPU quota assignment, maximum GPU device allocation, and weight assigned that determines the fairshare of over-quota resources.

object or null

Defines the CPU quota assignment in millicores (1000 millicores = 1 CPU core), maximum CPU allocation, and weight.

object or null

Defines the CPU memory quota assignment, maximum allocation, and weight.

rank
string or null
Default: "MediumLow"

The scheduling rank of this org-unit within the node pool. Determines the scheduling order of workloads between org-units. Workloads in higher-ranked org-units are scheduled before workloads in lower-ranked org-units. For example, all workloads in rank "High" will be scheduled before all workloads in rank "Medium".

priority
string or null
Deprecated

Deprecated. Use rank instead. The scheduling priority for workloads in this node pool.

Responses
200

Updated

400

Bad request.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

patch/api/v1/org-unit/departments/{departmentId}/resources
Request samples
application/json
[
  • {
    }
]
Response samples
application/json
[
  • {
    }
]

Get department metrics data.

Retrieves department data metrics from the metrics database. Use in reporting and analysis tools.

SecuritybearerAuth
Request
path Parameters
departmentId
required
string.*

The id of the department.

Example: 1
query Parameters
metricType
required
Array of strings (OrgUnitMetricType)

Specify which data to request.

Items Enum: "GPU_QUOTA" "CPU_QUOTA_MILLICORES" "CPU_MEMORY_QUOTA_MB" "GPU_ALLOCATION" "CPU_ALLOCATION_MILLICORES" "CPU_MEMORY_ALLOCATION_MB" "GPU_MEMORY_UTILIZATION"
start
required
string <date-time>

Start date of time range to fetch data in ISO 8601 timestamp format.

Example: start=2023-06-06T12:09:18.211Z
end
required
string <date-time>

End date of time range to fetch data in ISO 8601 timestamp format.

Example: end=2023-06-07T12:09:18.211Z
numberOfSamples
integer [ 0 .. 1000 ]
Default: 20

The number of samples to take in the specified time range.

Example: numberOfSamples=20
nodepoolName
string

Filter using the nodepool.

Example: nodepoolName=default
Responses
200

Executed successfully.

207

Partial success.

400

Bad request.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

get/api/v1/org-unit/departments/{departmentId}/metrics
Response samples
{
  • "measurements": [
    ]
}

Get departments telemetry

SecuritybearerAuth
Request
query Parameters
clusterId
string <uuid>

Filter using the Universally Unique Identifier (UUID) of the cluster.

Example: clusterId=d73a738f-fab3-430a-8fa3-5241493d7128
nodepoolName
string

Filter using the nodepool.

Example: nodepoolName=default
departmentId
string

Filter using the department id.

Example: departmentId=1
groupBy
Array of strings <= 2 items

department fields to group the data by

Items Value: "CLUSTER_ID"
telemetryType
required
string (OrgUnitTelemetryType)

specifies what data to request

Enum: "GPU_QUOTA" "CPU_QUOTA" "MEMORY_QUOTA" "GPU_ALLOCATION" "CPU_ALLOCATION" "MEMORY_ALLOCATION" "GPU_ALLOCATION_NON_PREEMPTIBLE" "CPU_ALLOCATION_NON_PREEMPTIBLE" "MEMORY_ALLOCATION_NON_PREEMPTIBLE"
Responses
200

Executed successfully.

400

Bad request.

401

Unauthorized

403

Forbidden

503

unexpected error

get/api/v1/org-unit/departments/telemetry
Response samples
application/json
{
  • "type": "ALLOCATION_RATIO",
  • "timestamp": "2023-06-06 12:09:18.211",
  • "values": [
    ]
}

Count departments

count departments

SecuritybearerAuth
Request
query Parameters
filterBy
Array of strings

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: filterBy=name!=some-name
Responses
200

ok

400

Bad request.

401

Unauthorized

403

Forbidden

503

unexpected error

get/api/v1/org-unit/departments/count
Response samples
application/json
{
  • "count": 1
}

Get departments node pool resources

List departments node pool resources

SecuritybearerAuth
Request
query Parameters
filterBy
Array of strings

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: filterBy=nodePoolName!=some-name
sortBy
string (DepartmentNodePoolResourcesFilterSortFields)

Sort results by a parameters.

Enum: "nodePoolName" "nodePoolId" "orgUnitId" "orgUnitName" "clusterId" "gpuDeserved" "gpuOverQuotaWeight"
sortOrder
string
Default: "asc"

Sort results in descending or ascending order.

Enum: "asc" "desc"
offset
integer <int32>

The offset of the first item returned in the collection.

Example: offset=100
limit
integer <int32> [ 1 .. 500 ]
Default: 50

The maximum number of entries to return.

search
string

Filter results by a free text search.

Example: search=test project
Responses
200

ok

400

Bad request.

401

Unauthorized

403

Forbidden

503

unexpected error

get/api/v1/org-unit/departments/node-pool-resources
Response samples
application/json
{
  • "nodePoolResources": [
    ],
  • "next": 1
}

Count departments node pool resources

Count departments node pool resources

SecuritybearerAuth
Request
query Parameters
filterBy
Array of strings

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: filterBy=nodePoolName!=some-name
search
string

Filter results by a free text search.

Example: search=test project
Responses
200

ok

400

Bad request.

401

Unauthorized

403

Forbidden

503

unexpected error

get/api/v1/org-unit/departments/node-pool-resources/count
Response samples
application/json
{
  • "count": 1
}

Patch multiple departments node pool resources in batch.

Partially updates node pool resource quotas for multiple departments in a single request.

SecuritybearerAuth
Request
Request Body schema: application/json
required

Batch of department resources patch requests.

required
Array of objects (NodePoolResourcesPatchRequest) [ 1 .. 100 ] items

Array of node pool resources patch requests.

Responses
200

Batch patch processed. Returns succeeded and failed items with totals and a batch id.

400

Bad request.

401

Unauthorized

403

Forbidden

500

unexpected error

503

unexpected error

post/api/v1/org-unit/departments/node-pool-resources/batch-patch
Request samples
application/json
{
  • "patchRequests": [
    ]
}
Response samples
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "succeeded": [
    ],
  • "failed": [
    ],
  • "totalRequested": 2,
  • "totalSuccessful": 1,
  • "totalFailed": 1
}

Get metrics for all departments.Deprecated

Get metrics for all departments in the cluster. Use a time range to return historical data (optional). If you use a start date, an end date is required.

SecuritybearerAuth
Request
path Parameters
clusterUuid
required
string <uuid> non-empty

The Universally Unique Identifier (UUID) of the cluster.

Example: 9f55255e-11ed-47c7-acef-fc4054768dbc
query Parameters
start
string <date-time>

Start of time range to fetch data from in UTC format.

Example: start=2023-06-06 12:09:18.211
end
string <date-time>

End of time range to fetch data from in UTC format.

Example: end=2023-06-07 12:09:18.211
numberOfSamples
integer [ 0 .. 1000 ]
Default: 20

The number of samples to take in the specified time range.

Example: numberOfSamples=20
nodepoolName
string

Filter by unique nodepool name.

Example: nodepoolName=default
Responses
200

Successfully retrieved metrics for all departments.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

get/v1/k8s/clusters/{clusterUuid}/departments/metrics
Response samples
application/json
{
  • "data": [
    ],
  • "timeRange": {
    }
}

Get metrics for a specific department.Deprecated

Get metrics for a specific department in the cluster. Use a time range to return historical data (optional). If you use a start date, an end date is required.

SecuritybearerAuth
Request
path Parameters
clusterUuid
required
string <uuid> non-empty

The Universally Unique Identifier (UUID) of the cluster.

Example: 9f55255e-11ed-47c7-acef-fc4054768dbc
departmentId
required
string.*

The id of the department.

Example: 1
query Parameters
start
string <date-time>

Start of time range to fetch data from in UTC format.

Example: start=2023-06-06 12:09:18.211
end
string <date-time>

End of time range to fetch data from in UTC format.

Example: end=2023-06-07 12:09:18.211
numberOfSamples
integer [ 0 .. 1000 ]
Default: 20

The number of samples to take in the specified time range.

Example: numberOfSamples=20
nodepoolName
string

Filter by unique nodepool name.

Example: nodepoolName=default
Responses
200

Successfully retrieved metrics for the department.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

get/v1/k8s/clusters/{clusterUuid}/departments/{departmentId}/metrics
Response samples
application/json
{
  • "metadata": {
    },
  • "current": {
    },
  • "timeRange": {
    }
}

List all departments.Deprecated

List all the departments managed by the tenant on a specific cluster.

SecuritybearerAuth
Request
path Parameters
clusterId
required
string

The Universally Unique Identifier (UUID) of the cluster.

Example: 9f55255e-11ed-47c7-acef-fc4054768dbc
query Parameters
excludePermissions
boolean

Backward compatibility of the departmentAdmins field. If true, the departmentAdmins field in the returned departments is not set. If false, the departmentAdmins is set in the returned departments.

Example: excludePermissions=true
memoryUnitMb
boolean

Memory returned in MB. When set to false (default) memory will be returned in MiB.

Example: memoryUnitMb=true
Responses
200

Successfully retrieved a list of Departments.

get/v1/k8s/clusters/{clusterId}/departments
Response samples
application/json
[
  • {
    }
]

Set the department admins.Deprecated

Deprecated. Instead, use the accessrules API to add the department-admin permissions to a specific subject.

SecuritybearerAuth
Request
path Parameters
clusterId
required
string

The unique uuid identifying the cluster.

Example: 9f55255e-11ed-47c7-acef-fc4054768dbc
department-id
required
integer

The unique id identifying the department.

Example: 2
Request Body schema: application/json
required
departmentId
integer <int32>

The unique id identifying the department.

departmentAdmins
Array of strings

Id's of users with department admin role that are assigned to managed the department

Responses
201

Department admin set successfully.

400

Bad request.

401

Unauthenticated

403

Forbidden

put/v1/k8s/clusters/{clusterId}/departments/{department-id}/access-control
Request samples
application/json
{
  • "departmentId": 2,
  • "departmentAdmins": [
    ]
}
Response samples
application/json
{
  • "departmentId": 2,
  • "departmentAdmins": [
    ]
}
➔ Next to Reports