> ## Documentation Index > Fetch the complete documentation index at: https://docs.nscale.com/llms.txt > Use this file to discover all available pages before exploring further. # List node pools > List node pools. Results are ordered by exact display name and then by public resource ID. Repeated values within one status filter are combined with OR; different filter classes are combined with AND. ## OpenAPI ````yaml /openapi/nks-openapi.yaml get /api/v1/nodepools openapi: 3.0.3 info: title: NKS API description: |- The NKS API provides Kubernetes clusters, node pools, and platform release catalog entries. version: 0.1.0 servers: - url: https://nks.nks.europe-west4.nscale.com description: Production security: [] paths: /api/v1/nodepools: description: Manages top-level project-scoped cluster node pools. get: tags: - Node Pools summary: List node pools description: |- List node pools. Results are ordered by exact display name and then by public resource ID. Repeated values within one status filter are combined with OR; different filter classes are combined with AND. operationId: listNodePools parameters: - $ref: '#/components/parameters/tagSelectorParameter' - $ref: '#/components/parameters/organizationIDQueryParameter' - $ref: '#/components/parameters/projectIDQueryParameter' - $ref: '#/components/parameters/clusterIDQueryParameter' - $ref: '#/components/parameters/regionIDQueryParameter' - $ref: '#/components/parameters/nameQueryParameter' - $ref: '#/components/parameters/provisioningStatusQueryParameter' - $ref: '#/components/parameters/healthStatusQueryParameter' - $ref: '#/components/parameters/deletingQueryParameter' responses: '200': $ref: '#/components/responses/nodePoolsV1Response' '400': $ref: '#/components/responses/badRequestResponse' '401': $ref: '#/components/responses/unauthorizedResponse' '403': $ref: '#/components/responses/forbiddenResponse' '500': $ref: '#/components/responses/internalServerErrorResponse' security: - oauth2Authentication: [] components: parameters: tagSelectorParameter: name: tag in: query description: |- A set of tags to match against resources in the form "name=value", thus when encoded you get "?tag=foo%3Dcat&tag=bar%3Ddog". schema: type: array items: type: string organizationIDQueryParameter: name: organizationID in: query description: Allows resources to be filtered by organization. schema: type: array items: type: string projectIDQueryParameter: name: projectID in: query description: Allows resources to be filtered by project. schema: type: array items: type: string clusterIDQueryParameter: name: clusterID in: query description: Allows node pools to be filtered by cluster. schema: type: array items: type: string regionIDQueryParameter: name: regionID in: query description: >- Allows resources to be filtered by region. For platform releases, matches releases available in any supplied region. schema: type: array items: type: string nameQueryParameter: name: name in: query description: >- Filters resources by exact, case-sensitive display name. Every matching resource is returned because display names are not unique. schema: $ref: '#/components/schemas/kubernetesLabelValue' provisioningStatusQueryParameter: name: provisioningStatus in: query description: >- Filters resources by UNI provisioning status. Repeat the parameter to match any supplied value. style: form explode: true schema: type: array uniqueItems: true items: $ref: '#/components/schemas/resourceProvisioningStatus' healthStatusQueryParameter: name: healthStatus in: query description: >- Filters resources by UNI health status. Repeat the parameter to match any supplied value. style: form explode: true schema: type: array uniqueItems: true items: $ref: '#/components/schemas/resourceHealthStatus' deletingQueryParameter: name: deleting in: query description: >- Filters by deletion state. True returns terminating resources, false returns non-terminating resources, and omission returns both. schema: type: boolean responses: nodePoolsV1Response: description: A list of node pools. content: application/json: schema: $ref: '#/components/schemas/nodePoolsV1Read' example: - metadata: id: 600f9b41-1a97-4b85-b69f-901839678772 generation: 5 name: workers-a organizationId: 9a8c6370-4065-4d4a-9da0-7678df40cd9d projectId: e36c058a-8eba-4f5b-91f4-f6ffb983795c creationTime: '2026-05-14T10:15:00.000Z' provisioningStatus: provisioned provisioningStatusDetail: reason: Provisioned message: node pool is available healthStatus: healthy healthStatusDetail: reason: Healthy message: node pool workers are ready tags: - name: role value: worker spec: clusterId: 1e44f19a-21a9-43cc-a460-5d6f21247f65 provisioningMode: compute replicas: 3 compute: flavorId: g.8.standard taints: - key: nvidia.com/gpu effect: NoSchedule labels: accelerator: nvidia-h100 status: regionId: uk-lon-1 observedGeneration: 5 kubernetesVersion: v1.32.3 desiredReplicas: 3 currentReplicas: 3 readyReplicas: 3 badRequestResponse: description: |- Request body failed schema validation, or the request does not contain all the required fields. content: application/json: schema: $ref: '#/components/schemas/error' example: error: invalid_request error_description: request body invalid trace_id: 57bc14d9bd461f0b5a72db830149b67a unauthorizedResponse: description: Authentication failed or the access token has expired. content: application/json: schema: $ref: '#/components/schemas/error' example: error: access_denied error_description: authentication failed trace_id: 57bc14d9bd461f0b5a72db830149b67a forbiddenResponse: description: >- Request was denied by authorization, this may be caused by the authorization token not having the required scope for an API, or the user doesn't have the necessary privileges on the provider platform. content: application/json: schema: $ref: '#/components/schemas/error' example: error: forbidden error_description: user credentials do not have the required privileges trace_id: 57bc14d9bd461f0b5a72db830149b67a internalServerErrorResponse: description: >- An unexpected or unhandled error occurred. This may be a transient error and may succeed on a retry. If this isn't the case, please report it as an issue. content: application/json: schema: $ref: '#/components/schemas/error' example: error: server_error error_description: failed to token claim trace_id: 57bc14d9bd461f0b5a72db830149b67a schemas: kubernetesLabelValue: description: >- A valid Kubernetes label value, typically used for resource names that can be indexed in the database. type: string pattern: ^[0-9A-Za-z](?:[0-9A-Za-z-_.]{0,61}[0-9A-Za-z])?$ resourceProvisioningStatus: description: The provisioning state of a resource. type: string enum: - pending - provisioning - provisioned - deprovisioning - error resourceHealthStatus: description: The health state of a resource. type: string enum: - unknown - healthy - degraded - error nodePoolsV1Read: description: A list of node pools. type: array items: $ref: '#/components/schemas/nodePoolV1Read' error: description: Generic error message, compatible with oauth2. type: object required: - error - error_description properties: error: description: >- A terse error string expanding on the HTTP error code. Errors are based on the OAuth 2.02 specification, but are expanded with proprietary status codes for APIs other than those specified by OAuth 2.02. type: string enum: - invalid_request - server_error - access_denied - not_found - conflict - method_not_allowed - unsupported_media_type - request_entity_too_large - unprocessable_content - forbidden error_description: description: Verbose message describing the error. type: string trace_id: description: Unique trace identifier for the request. type: string nodePoolV1Read: description: A cluster node pool. type: object required: - metadata - spec - status properties: metadata: $ref: '#/components/schemas/projectScopedResourceReadMetadataV1' spec: $ref: '#/components/schemas/nodePoolSpecV1' status: $ref: '#/components/schemas/nodePoolStatusV1' projectScopedResourceReadMetadataV1: description: >- Project-scoped resource read metadata with Kubernetes generation freshness. type: object required: - id - name - organizationId - projectId - creationTime - generation - provisioningStatus - healthStatus properties: id: description: Unique resource ID. type: string name: $ref: '#/components/schemas/kubernetesLabelValue' description: description: Optional human-readable resource description. type: string tags: $ref: '#/components/schemas/tagList' organizationId: description: Organization identifier the resource belongs to. type: string projectId: description: Project identifier the resource belongs to. type: string creationTime: description: Time the resource was created. type: string format: date-time createdBy: description: User who created the resource. type: string modifiedTime: description: Time the resource was updated. type: string format: date-time modifiedBy: description: User who updated the resource. type: string deletionTime: description: Time deletion was requested. type: string format: date-time generation: description: Current desired-state generation of the resource. type: integer format: int64 minimum: 0 provisioningStatus: $ref: '#/components/schemas/resourceProvisioningStatus' provisioningStatusDetail: $ref: '#/components/schemas/provisioningStatusDetail' healthStatus: $ref: '#/components/schemas/resourceHealthStatus' healthStatusDetail: $ref: '#/components/schemas/healthStatusDetail' nodePoolSpecV1: description: Desired node pool state. type: object additionalProperties: false required: - clusterId - provisioningMode - replicas properties: clusterId: description: Cluster this node pool belongs to. type: string provisioningMode: $ref: '#/components/schemas/nodePoolProvisioningModeV1' replicas: description: Desired worker replica count. type: integer minimum: 0 maximum: 2147483647 compute: $ref: '#/components/schemas/nodePoolComputeV1' reservation: $ref: '#/components/schemas/nodePoolReservationV1' taints: description: >- Kubernetes taints applied to node pool workers as they join the cluster. Taints are not continuously reconciled onto running nodes, so a change applies to newly created workers only and rolls the pool's existing workers so the new taints take effect. type: array maxItems: 64 items: $ref: '#/components/schemas/nodePoolTaintV1' labels: $ref: '#/components/schemas/nodePoolLabelsV1' nodePoolStatusV1: description: Product-specific resolved placement and observed node pool state. type: object required: - regionId properties: regionId: description: Resolved region inherited from the parent cluster. type: string observedGeneration: description: >- Most recent resource generation coherently projected into status. Omitted until a status projection completes. type: integer format: int64 minimum: 0 kubernetesVersion: description: Kubernetes version applied to the node pool's workers. type: string desiredReplicas: description: Desired worker replica count for the node pool. type: integer minimum: 0 currentReplicas: description: Current worker replica count. type: integer minimum: 0 readyReplicas: description: Ready worker replica count. type: integer minimum: 0 upToDateReplicas: description: Worker replica count running the current node pool template. type: integer minimum: 0 reservation: $ref: '#/components/schemas/nodePoolReservationStatusV1' release: $ref: '#/components/schemas/nodePoolReleaseStatusV1' tagList: description: A list of tags. type: array items: $ref: '#/components/schemas/tag' provisioningStatusDetail: description: |- Human-facing detail about the current provisioning state: a machine-classifiable reason drawn from a closed vocabulary, and a user-safe human-readable message. Derived from the resource's status and supplements the coarse provisioningStatus; never stored. type: object required: - reason - message properties: reason: $ref: '#/components/schemas/provisioningStatusReason' message: description: A user-safe, human-readable description of the provisioning state. type: string healthStatusDetail: description: >- Human-facing detail about the current health state: a machine-classifiable reason drawn from a closed vocabulary, and a user-safe human-readable message (e.g. "2/12 nodes are down"). Derived from the resource's status and supplements the coarse healthStatus; never stored. type: object required: - reason - message properties: reason: $ref: '#/components/schemas/healthStatusReason' message: description: A user-safe, human-readable description of the health state. type: string nodePoolProvisioningModeV1: description: Capacity source used to provision node pool workers. type: string enum: - compute - reservation nodePoolComputeV1: description: Compute-backed worker capacity selector. type: object properties: flavorId: description: Compute flavor ID. Required when provisioningMode is compute. type: string minLength: 1 maxLength: 128 nodePoolReservationV1: description: Reservation-backed worker capacity selector. type: object properties: reservationId: description: >- Reservation ID to consume capacity from. Required when provisioningMode is reservation. type: string constraints: $ref: '#/components/schemas/nodePoolPlacementConstraintsV1' nodePoolTaintV1: description: >- Kubernetes taint applied to a node pool worker as it joins the cluster. The taint is applied during worker node registration, so it takes effect once during node initialization and is not reconciled onto running nodes afterwards. type: object required: - key - effect properties: key: description: Taint key. type: string minLength: 1 maxLength: 317 pattern: >- ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*\/)?([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9]$ value: description: Taint value. type: string maxLength: 63 pattern: ^(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])?$ effect: description: Taint effect. type: string enum: - NoSchedule - PreferNoSchedule - NoExecute nodePoolLabelsV1: description: >- Kubernetes labels applied to node pool workers as they join the cluster. Labels are not continuously reconciled onto running nodes, so a change applies to newly created workers only and rolls the pool's existing workers so the new labels take effect. type: object maxProperties: 64 additionalProperties: description: >- Label value. Kubernetes permits an empty value, so an omitted value registers the label with the empty string. type: string maxLength: 63 pattern: ^(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])?$ nodePoolReservationStatusV1: description: Observed reservation-backed worker capacity. type: object properties: reservationId: description: Selected Reservation ID. type: string placementId: description: Node-pool-managed Reservation placement ID. type: string nodePoolReleaseStatusV1: description: Pinned platform release's identity, deprecation, and withdrawal state. type: object additionalProperties: false required: - appliedId - kubernetesVersion properties: appliedId: description: Pinned platform release ID. type: string kubernetesVersion: description: Pinned platform release's Kubernetes version. type: string deprecated: description: Whether the pinned platform release is currently deprecated. type: boolean withdrawn: description: Whether operators have withdrawn the pinned platform release. type: boolean withdrawalReason: $ref: '#/components/schemas/platformReleaseWithdrawalReasonV1' description: >- Stable machine-readable reason operators withdrew the pinned platform release. withdrawalMessage: description: >- Customer-safe explanation of why operators withdrew the pinned platform release. type: string maxLength: 32768 tag: description: >- A tag mapping arbitrary names to values. These have no special meaning for any component are are intended for use by end users to add additional context to a resource, for example to categorize it. type: object required: - name - value properties: name: description: A unique tag name. type: string value: description: The value of the tag. type: string provisioningStatusReason: description: |- A closed, generic classification of a resource's provisioning state, finer-grained than provisioningStatus. This vocabulary is owned by the platform and is the same across all resources; domain-specific state (e.g. an instance's lifecycle phase) is carried on other mechanisms and never appears here. type: string enum: - Provisioning - Provisioned - Errored - Deprovisioning - Deprovisioned - DependencyNotReady - DependencyFailed - DependencyNotFound healthStatusReason: description: >- A closed, generic classification of a resource's health — the raw health condition reason, finer-grained than the coarse healthStatus. Owned by the platform and the same across all resources. type: string enum: - Healthy - Degraded - Unknown nodePoolPlacementConstraintsV1: description: Immutable topology placement policy for a reservation-backed node pool. type: object additionalProperties: false required: - policy properties: policy: description: >- Pack fills domains sequentially; spread distributes hosts across domains. type: string enum: - pack - spread maxSkew: description: >- Maximum difference in host count between domains. Valid only for spread. type: integer minimum: 1 maximum: 2147483647 minDomains: description: Minimum topology domains receiving a host. Valid only for spread. type: integer minimum: 1 maximum: 2147483647 whenUnsatisfiable: description: >- Fail rejects an unsatisfied spread; bestEffort chooses the closest layout. type: string enum: - fail - bestEffort platformReleaseWithdrawalReasonV1: description: Stable machine-readable reason operators withdrew a platform release. type: string enum: - SecurityIssue - FunctionalRegression - CompatibilityIssue - ComplianceIssue - OperationalIssue - Other securitySchemes: oauth2Authentication: type: oauth2 flows: authorizationCode: authorizationUrl: /oauth2/v2/authorization tokenUrl: /oauth2/v2/token scopes: {} ````