> This page is for Self-Hosted, version v3.0 (default). > For other versions, use one of these documentation indexes: > - v3.0 (default): https://docs.nvidia.com/run-ai/self-hosted/v3.0/llms.txt > - v2.26: https://docs.nvidia.com/run-ai/self-hosted/v2.26/llms.txt > - v2.25: https://docs.nvidia.com/run-ai/self-hosted/v2.25/llms.txt > - v2.24: https://docs.nvidia.com/run-ai/self-hosted/v2.24/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/run-ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/run-ai/_mcp/server. # Get projects GET http://localhost:8080/api/v1/org-unit/projects List projects Reference: https://docs.nvidia.com/run-ai/self-hosted/reference/rest-api/endpoints/organizations/projects/get-projects ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication ## Request ### Query parameters - `filterBy` (list of string, optional) — 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 >=. - `sortBy` (enum, optional) — Sort results by a parameters. - Allowed values: `name`, `clusterId`, `departmentId`, `parentId`, `parentName`, `phase`, `totalGpuQuota`, `gpuAllocated`, `createdAt`, `avgGpuAllocation24h`, `avgGpuUtilization24h`, `avgGpuMemoryUtilization24h`, `avgGpuAllocation7d`, `avgGpuUtilization7d`, `avgGpuMemoryUtilization7d`, `avgGpuAllocation30d`, `avgGpuUtilization30d`, `avgGpuMemoryUtilization30d` - `sortOrder` (enum, optional, default: asc) — Sort results in descending or ascending order. - Allowed values: `asc`, `desc` - `offset` (integer, optional) — The offset of the first item returned in the collection. - `limit` (integer, optional, default: 50) — The maximum number of entries to return. - `search` (string, optional) — Filter results by a free text search. ## Response ### 200 ok - `projects` (list of Project, required) - `next` (integer, optional) ## Errors ### 400 Bad Request Error Bad request. - `code` (integer, required) - `message` (string, required) - `details` (string, optional) ### 401 Unauthorized Error Unauthorized - `code` (integer, required) - `message` (string, required) - `details` (string, optional) ### 403 Forbidden Error Forbidden - `code` (integer, required) - `message` (string, required) - `details` (string, optional) ### 503 Service Unavailable Error unexpected error - `code` (integer, required) - `message` (string, required) - `details` (string, optional) ## Types ### Project Updatable fields - `description` (string, required) — The description of the project. - `id` (string, required) - `name` (string, required) - `clusterId` (string, required) — The id of the cluster. - `parentId` (string, required) — department parent uuid - `enforceRunaiScheduler` (boolean, required) — a flag to enforce that all pods in this namespace will be scheduled with runai-scheduler. Supported for cluster v2.21+ - `status` (ProjectStatus, required) - `totalResources` (TotalResources, required) - `createdAt` (datetime, required) - `updatedAt` (datetime, required) - `effective` (ProjectEffective, required) - `resources` (list of Resources, required) — Resources assigned to this Organization per Node Pool - `schedulingRules` (SchedulingRules, optional) — 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` (list of string, optional, nullable) — An ordered list of node pools that defines the default scheduling preference for workloads in this project. 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. - `nodeTypes` (NodeTypesPerWorkload, optional) — Deprecated: use a workload policy node selector to target node types instead. 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. - `requestedNamespace` (string, optional, nullable) — the project's namespace only if requested - `createdBy` (string, optional) - `updatedBy` (string, optional) - `parent` (DepartmentProjectParent, optional) — Department or project parent - `overtimeData` (OvertimeData, optional) ### ProjectStatus - `namespace` (string, optional, nullable) — the project's namespace - `phase` (enum, optional) — the project's phase - Allowed values: `Creating`, `Updating`, `Deleting`, `Deleted`, `Initializing`, `Ready`, `NotReady`, `Unknown` - `phaseMessage` (string, optional, nullable) — the project's phase message - `lastUpdatedTime` (datetime, optional, nullable) - `nodePoolQuotaStatuses` (list of QuotaStatusNodePool, optional) - `quotaStatus` (QuotaStatus, optional) — Sum of all quota statuses of all the node pools - `additionalStatusData` (map from string to any, optional, nullable) ### TotalResources - `gpuQuota` (double, optional, nullable) — Total gpu quota of the org unit - `cpuQuota` (double, optional, nullable) — Total cpu quota of the org unit in Millicores - `memoryQuota` (double, optional, nullable) — Total memory quota of the org unit in MB ### ProjectEffective - `schedulingRules` (SchedulingRules, optional) — 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` (list of string, optional, nullable) — default order of node pools for workloads. will be enforced if no list is defined in workload policy - `nodeTypes` (NodeTypesPerWorkload, optional) — Deprecated: use a workload policy node selector to target node types instead. 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. ### Resources - `gpu` (ResourcesGpu, required) - `nodePool` (ResourcesNodePool, optional, nullable) — The node pool to which this resource configuration applies. - `cpu` (ResourcesCpu, optional, nullable) - `memory` (ResourcesMemory, optional, nullable) - `rank` (string, optional, nullable, 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". ### 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. - `interactiveJobTimeLimitSeconds` (integer, optional, nullable) — interactive job time limit in seconds - `interactiveJobMaxIdleDurationSeconds` (integer, optional, nullable) — interactive job max idle duration in seconds - `interactiveJobPreemptIdleDurationSeconds` (integer, optional, nullable) — interactive job preempt idle duration in seconds - `trainingJobMaxIdleDurationSeconds` (integer, optional, nullable) — training job max idle duration in seconds - `trainingJobTimeLimitSeconds` (integer, optional, nullable) — training job time limit in seconds ### NodeTypesPerWorkload Deprecated: use a workload policy node selector to target node types instead. 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. - `training` (list of string, optional) — ids of the node types for training workloads - `workspace` (list of string, optional) — ids of the node types for workspace workloads - `names` (map from string to string, optional, nullable) — mapping of ids to names ### DepartmentProjectParent Department or project parent - `id` (string, required) - `name` (string, required) - `parent` (DepartmentProjectParent, optional) — Department or project parent ### OvertimeData - `range24hData` (OvertimeRangeData, optional, nullable) — Average data for the specified time range, or for the lifetime of the project/department if it exists for less than the time range. - `range7dData` (OvertimeRangeData, optional, nullable) — Average data for the specified time range, or for the lifetime of the project/department if it exists for less than the time range. - `range30dData` (OvertimeRangeData, optional, nullable) — Average data for the specified time range, or for the lifetime of the project/department if it exists for less than the time range. ### QuotaStatusNodePool Sum of all quota statuses of all the node pools - `nodePoolName` (string, required) — The node pool name which the current quota status refers to - `nodePoolId` (string, required) — The node pool id which the current quota status refers to - `allocated` (QuotaStatusResource, optional) - `allocatedNonPreemptible` (QuotaStatusResource, optional) - `requested` (QuotaStatusResource, optional) ### QuotaStatus Sum of all quota statuses of all the node pools - `allocated` (QuotaStatusResource, optional) - `allocatedNonPreemptible` (QuotaStatusResource, optional) - `requested` (QuotaStatusResource, optional) ### ResourcesGpu - `deserved` (double, required, default: 0) — The GPU quota assigned to this org-unit. - `limit` (double, optional, nullable) — The maximum GPU device allocation the org-unit can get from this node pool, representing the maximum sum of assigned quota and over-quota GPUs. Set to null for unlimited. - `overQuotaWeight` (double, optional, nullable) — The weight assigned to determine the org-unit's share of over-quota resources within its rank. When multiple org-units share the same rank in a node pool, resources are distributed proportionally based on their weights. Valid values: 1–20. Requires over-quota weight to be enabled. When enabled, the default is 2. See [GPU over quota](/run-ai/self-hosted/documentation/platform-management/manage-ai-initiatives/organization/projects) for more details. ### ResourcesNodePool The node pool to which this resource configuration applies. - `id` (string, required) — The ID of the node pool. - `name` (string, optional) — The name of the node pool. ### ResourcesCpu - `deserved` (double, optional, nullable) — The resource quota assigned to this org-unit. - `limit` (double, optional, nullable) — The maximum resource allocation for this org-unit. Set to null for unlimited. - `overQuotaWeight` (double, optional, nullable) — The weight assigned to determine the org-unit's share of over-quota resources within its rank. When multiple org-units share the same rank in a node pool, resources are distributed proportionally based on their weights. Valid values: 1–20. Requires over-quota weight to be enabled. When enabled, the default is 2. See [GPU over quota](/run-ai/self-hosted/documentation/platform-management/manage-ai-initiatives/organization/projects) for more details. ### ResourcesMemory - `units` (enum, required) — The unit of measurement for CPU memory values. - Allowed values: `Mib`, `MB`, `GB` - `deserved` (double, optional, nullable) — The resource quota assigned to this org-unit. - `limit` (double, optional, nullable) — The maximum resource allocation for this org-unit. Set to null for unlimited. - `overQuotaWeight` (double, optional, nullable) — The weight assigned to determine the org-unit's share of over-quota resources within its rank. When multiple org-units share the same rank in a node pool, resources are distributed proportionally based on their weights. Valid values: 1–20. Requires over-quota weight to be enabled. When enabled, the default is 2. See [GPU over quota](/run-ai/self-hosted/documentation/platform-management/manage-ai-initiatives/organization/projects) for more details. ### OvertimeRangeData Average data for the specified time range, or for the lifetime of the project/department if it exists for less than the time range. - `averageGpuAllocation` (double, optional) — The average gpu devices allocation of the project/department. - `averageGpuUtilization` (double, optional) — The average gpu utilization percentage of the project/department. - `averageGpuMemoryUtilization` (double, optional, nullable) — The average gpu memory utilization percentage of the project/department. Only available for cluster versions >= 2.22. - `updatedAt` (datetime, optional) ### QuotaStatusResource - `gpu` (double, optional) — The number of GPUs (allocated/requested/...). - `cpu` (double, optional) — CPU in Millicores (allocated/requested/...). - `memory` (double, optional) — Memory in MB (allocated/requested/...). ## Examples **Response** ```json { "projects": [ { "description": "string", "id": "33", "name": "organization1", "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210", "parentId": "53a9228e-a722-420d-a102-9dc90da2efca", "enforceRunaiScheduler": true, "status": { "namespace": "runai-proj1", "phase": "Creating", "phaseMessage": "Project is ready", "lastUpdatedTime": "2024-01-15T09:30:00Z", "nodePoolQuotaStatuses": [ { "nodePoolName": "string", "nodePoolId": "string", "allocated": { "gpu": 0, "cpu": 1000, "memory": 1000 }, "allocatedNonPreemptible": { "gpu": 0, "cpu": 1000, "memory": 1000 }, "requested": { "gpu": 0, "cpu": 1000, "memory": 1000 } } ], "quotaStatus": { "allocated": { "gpu": 0, "cpu": 1000, "memory": 1000 }, "allocatedNonPreemptible": { "gpu": 0, "cpu": 1000, "memory": 1000 }, "requested": { "gpu": 0, "cpu": 1000, "memory": 1000 } }, "additionalStatusData": {} }, "totalResources": { "gpuQuota": 1.1, "cpuQuota": 1.1, "memoryQuota": 1.1 }, "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:30:00Z", "effective": { "schedulingRules": { "interactiveJobTimeLimitSeconds": 100, "interactiveJobMaxIdleDurationSeconds": 100, "interactiveJobPreemptIdleDurationSeconds": 100, "trainingJobMaxIdleDurationSeconds": 100, "trainingJobTimeLimitSeconds": 100 }, "defaultNodePools": [ "string" ], "nodeTypes": { "training": [ "string" ], "workspace": [ "string" ], "names": {} } }, "resources": [ { "gpu": { "deserved": 1000, "limit": 0, "overQuotaWeight": 2 }, "nodePool": { "id": "22", "name": "default" }, "cpu": { "deserved": 1000, "limit": 0, "overQuotaWeight": 2 }, "memory": { "units": "Mib", "deserved": 1000, "limit": 0, "overQuotaWeight": 2 }, "rank": "High" } ], "schedulingRules": { "interactiveJobTimeLimitSeconds": 100, "interactiveJobMaxIdleDurationSeconds": 100, "interactiveJobPreemptIdleDurationSeconds": 100, "trainingJobMaxIdleDurationSeconds": 100, "trainingJobTimeLimitSeconds": 100 }, "defaultNodePools": [ "string" ], "nodeTypes": { "training": [ "string" ], "workspace": [ "string" ], "names": {} }, "requestedNamespace": "runai-proj1", "createdBy": "string", "updatedBy": "string", "parent": { "id": "9f55253e-11ed-47c7-acef-fc4054768dbc", "name": "organization1" }, "overtimeData": { "range24hData": { "averageGpuAllocation": 10, "averageGpuUtilization": 95, "averageGpuMemoryUtilization": 95, "updatedAt": "2021-08-01T00:00:00Z" }, "range7dData": { "averageGpuAllocation": 10, "averageGpuUtilization": 95, "averageGpuMemoryUtilization": 95, "updatedAt": "2021-08-01T00:00:00Z" }, "range30dData": { "averageGpuAllocation": 10, "averageGpuUtilization": 95, "averageGpuMemoryUtilization": 95, "updatedAt": "2021-08-01T00:00:00Z" } } } ], "next": 1 } ``` **SDK Code** ```python import requests url = "http://localhost:8080/api/v1/org-unit/projects" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'http://localhost:8080/api/v1/org-unit/projects'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "http://localhost:8080/api/v1/org-unit/projects" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("http://localhost:8080/api/v1/org-unit/projects") http = Net::HTTP.new(url.host, url.port) request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("http://localhost:8080/api/v1/org-unit/projects") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'http://localhost:8080/api/v1/org-unit/projects', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("http://localhost:8080/api/v1/org-unit/projects"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "http://localhost:8080/api/v1/org-unit/projects")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```