> ## 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. # Get placement > Get a placement. ## OpenAPI ````yaml /openapi/reservation-openapi.yaml get /api/v2/placements/{placementID} openapi: 3.0.3 info: title: Unikorn Reservation API description: |- Reservation service provides topology-aware bare metal GPU reservation and placement, sitting atop UNI Region service resources. version: 0.5.0 servers: - url: https://reservation.nks.europe-west4.nscale.com description: Production - url: https://reservation.nks-stg.europe-west2.nscale.com description: Staging - url: https://reservation.nks-dev.glo1.nscale.com description: Development security: [] paths: /api/v2/placements/{placementID}: description: |- Manages project scoped placements of hosts from reservations. A placement consumes capacity from a reservation and drives pinned Region server creation for each selected host. parameters: - $ref: '#/components/parameters/placementIDParameter' get: tags: - Placements summary: Get placement description: Get a placement. operationId: getPlacement responses: '200': $ref: '#/components/responses/placementV2Response' '400': $ref: '#/components/responses/badRequestResponse' '401': $ref: '#/components/responses/unauthorizedResponse' '403': $ref: '#/components/responses/forbiddenResponse' '404': $ref: '#/components/responses/notFoundResponse' '500': $ref: '#/components/responses/internalServerErrorResponse' security: - oauth2Authentication: [] components: parameters: placementIDParameter: name: placementID in: path description: The placement ID. required: true schema: $ref: '#/components/schemas/kubernetesNameParameter' responses: placementV2Response: description: A placement. content: application/json: schema: $ref: '#/components/schemas/placementV2Read' example: metadata: id: b8ce034e-fccb-4d6c-a0e0-af3e3f346715 name: training-workers organizationId: 9a8c6370-4065-4d4a-9da0-7678df40cd9d projectId: e36c058a-8eba-4f5b-91f4-f6ffb983795c creationTime: '2026-04-28T11:03:12Z' createdBy: john.doe@example.com provisioningStatus: pending healthStatus: healthy tags: - name: workload value: training spec: count: 8 serverSpec: imageId: ubuntu-24.04 sshCertificateAuthorityId: 00de8f3c-77d6-424a-93c3-baf9153c7f21 networking: securityGroups: - 7ddfdbf0-bdbf-4630-9220-f1e6876f2dd0 constraints: policy: spread maxSkew: 1 minDomains: 3 whenUnsatisfiable: fail status: regionId: c7568e2d-f9ab-453d-9a3a-51375f78426b reservationId: a64f9269-36e0-4312-b8d1-52d93d569b7b networkId: 61f0ad85-3001-41cb-824a-e6a047668dfe readyHostCount: 0 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 notFoundResponse: description: Unable to find a resource. content: application/json: schema: $ref: '#/components/schemas/error' example: error: not_found error_description: the requested resource does not exist 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: kubernetesNameParameter: description: >- A Kubernetes name. Must be a valid DNS label containing only lower case characters, numbers or hyphens, start and end with a character or number, and be at most 63 characters in length. type: string minLength: 1 maxLength: 63 placementV2Read: description: A placement. type: object required: - metadata - spec - status properties: metadata: $ref: '#/components/schemas/projectScopedResourceReadMetadata' spec: $ref: '#/components/schemas/placementV2Spec' status: $ref: '#/components/schemas/placementV2Status' 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 projectScopedResourceReadMetadata: description: Metadata required by project scoped resource reads. allOf: - $ref: '#/components/schemas/organizationScopedResourceReadMetadata' - type: object required: - projectId properties: projectId: description: The project identifier the resource belongs to. type: string placementV2Spec: description: A placement's specification. type: object required: - count - constraints - serverSpec properties: count: description: Number of hosts to allocate from the reservation. type: integer minimum: 1 constraints: $ref: '#/components/schemas/placementConstraintsV2' readinessPolicy: $ref: '#/components/schemas/placementReadinessPolicyV2' serverSpec: $ref: '#/components/schemas/placementServerSpecV2' placementV2Status: description: Read only status information about a placement. type: object required: - regionId - reservationId - networkId properties: regionId: description: The region the placement belongs to. type: string reservationId: description: The reservation the placement allocates from. type: string networkId: description: The network the placement belongs to. type: string readyHostCount: description: Number of hosts whose Region server resources are ready. type: integer minimum: 0 organizationScopedResourceReadMetadata: description: Metadata required by organization scoped resource reads. allOf: - $ref: '#/components/schemas/resourceReadMetadata' - type: object required: - organizationId properties: organizationId: description: The organization identifier the resource belongs to. type: string placementConstraintsV2: description: Scheduling policy applied when selecting hosts from the reservation. type: object required: - policy properties: policy: $ref: '#/components/schemas/placementPolicyV2' maxSkew: description: |- Maximum difference in host count between any two domains. Applicable only when policy is spread. type: integer minimum: 1 minDomains: description: |- Minimum number of domains that must receive at least one selected host. Applicable only when policy is spread. Must be less than or equal to count. type: integer minimum: 1 whenUnsatisfiable: $ref: '#/components/schemas/whenUnsatisfiableV2' placementReadinessPolicyV2: description: Controls how current host readiness affects Placement selection. type: object default: mode: Prefer required: - mode properties: mode: $ref: '#/components/schemas/placementReadinessModeV2' placementServerSpecV2: description: Region server options applied to each pinned server. type: object required: - imageId properties: imageId: description: The image to use for each pinned server. type: string networking: $ref: '#/components/schemas/placementServerNetworkingV2' sshCertificateAuthorityId: description: The SSH certificate authority ID. type: string userData: description: |- Contains base64-encoded configuration information or scripts to use upon launch. type: string format: byte resourceReadMetadata: description: Metadata required by all resource reads. allOf: - $ref: '#/components/schemas/staticResourceMetadata' - type: object required: - provisioningStatus - healthStatus properties: deletionTime: description: The time the resource was deleted. type: string format: date-time provisioningStatus: $ref: '#/components/schemas/resourceProvisioningStatus' healthStatus: $ref: '#/components/schemas/resourceHealthStatus' placementPolicyV2: description: |- Pack fills domains sequentially, maximising locality. Spread distributes hosts as evenly as possible across domains. type: string enum: - pack - spread whenUnsatisfiableV2: description: |- Fail returns an error if the constraint cannot be fully satisfied. Best effort applies the constraint as closely as it can. type: string enum: - fail - bestEffort placementReadinessModeV2: description: |- Require only selects hosts that pass current readiness preflight. Prefer selects ready hosts first but may use structurally claimable hosts to satisfy the request. Ignore does not use readiness when selecting hosts. type: string enum: - Require - Prefer - Ignore placementServerNetworkingV2: description: Region server networking options applied to each pinned server. type: object properties: allowedSourceAddresses: description: |- A list of network prefixes that are allowed to egress from the server. By default, only packets from the server's network interface's IP address are allowed to enter the network. type: array items: type: string publicIP: description: Whether or not to provision a public IP. type: boolean securityGroups: description: A list of security group IDs. type: array items: type: string staticResourceMetadata: description: | This metadata is for resources that just exist, and don't require any provisioning and health status, but benefit from a standardized metadata format. type: object allOf: - $ref: '#/components/schemas/resourceMetadata' - type: object required: - id - creationTime properties: id: description: The unique resource ID. type: string creationTime: description: The time the resource was created. type: string format: date-time createdBy: description: The user who created the resource. type: string modifiedTime: description: The time a resource was updated. type: string format: date-time modifiedBy: description: The user who updated the resource. type: string resourceProvisioningStatus: description: The provisioning state of a resource. type: string enum: - unknown - pending - provisioning - provisioned - deprovisioning - error resourceHealthStatus: description: The health state of a resource. type: string enum: - unknown - healthy - degraded - error resourceMetadata: description: Metadata required for all API resource reads and writes. required: - name properties: name: $ref: '#/components/schemas/kubernetesLabelValue' description: description: >- The resource description, this optionally augments the name with more context. type: string tags: $ref: '#/components/schemas/tagList' 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])?$ tagList: description: A list of tags. type: array items: $ref: '#/components/schemas/tag' 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 securitySchemes: oauth2Authentication: type: oauth2 flows: authorizationCode: authorizationUrl: /oauth2/v2/authorization tokenUrl: /oauth2/v2/token scopes: {} ````