---
title: "List placements"
method: GET
path: "/api/v2/placements"
tags: ["Placements"]
---

# List placements

`GET /api/v2/placements`

List placements.

## Query parameters

- `tag` string[]
- `organizationID` string[]
- `projectID` string[]
- `regionID` string[]
- `reservationID` string[]
- `networkID` string[]

## Response `200`

A list of placements.

- PlacementV2Read[] — A list of placements.
  - `metadata` ProjectScopedResourceReadMetadata, required — Metadata required for all API resource reads and writes.
    - `name` string, required — A valid Kubernetes label value, typically used for resource names that can be indexed in the database.
    - `description` string — The resource description, this optionally augments the name with more context.
    - `tags` Tag[] — A list of tags.
      - `name` string, required — A unique tag name.
      - `value` string, required — The value of the tag.
    - `id` string, required — The unique resource ID.
    - `creationTime` string, date-time, required — The time the resource was created.
    - `createdBy` string — The user who created the resource.
    - `modifiedTime` string, date-time — The time a resource was updated.
    - `modifiedBy` string — The user who updated the resource.
    - `deletionTime` string, date-time — The time the resource was deleted.
    - `provisioningStatus` 'unknown' | 'provisioning' | 'provisioned' | 'deprovisioning' | 'error', required — The provisioning state of a resource.
    - `healthStatus` 'unknown' | 'healthy' | 'degraded' | 'error', required — The health state of a resource.
    - `organizationId` string, required — The organization identifier the resource belongs to.
    - `projectId` string, required — The project identifier the resource belongs to.
  - `spec` PlacementV2Spec, required — A placement's specification.
    - `count` integer, required — Number of hosts to allocate from the reservation.
    - `constraints` PlacementConstraintsV2, required — Scheduling policy applied when selecting hosts from the reservation.
      - `policy` 'pack' | 'spread', required — Pack fills domains sequentially, maximising locality. Spread distributes hosts as evenly as possible across domains.
      - `maxSkew` integer — Maximum difference in host count between any two domains. Applicable only when policy is spread.
      - `minDomains` integer — 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.
      - `whenUnsatisfiable` 'fail' | 'bestEffort' — Fail returns an error if the constraint cannot be fully satisfied. Best effort applies the constraint as closely as it can.
    - `readinessPolicy` PlacementReadinessPolicyV2 — Controls how current host readiness affects Placement selection.
      - `mode` 'Require' | 'Prefer' | 'Ignore', required — 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.
    - `serverSpec` PlacementServerSpecV2, required — Region server options applied to each pinned server.
      - `imageId` string, required — The image to use for each pinned server.
      - `networking` PlacementServerNetworkingV2 — Region server networking options applied to each pinned server.
        - `allowedSourceAddresses` string[] — 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.
        - `publicIP` boolean — Whether or not to provision a public IP.
        - `securityGroups` string[] — A list of security group IDs.
      - `sshCertificateAuthorityId` string — The SSH certificate authority ID.
      - `userData` string, byte — Contains base64-encoded configuration information or scripts to use upon launch.
  - `status` PlacementV2Status, required — Read only status information about a placement.
    - `regionId` string, required — The region the placement belongs to.
    - `reservationId` string, required — The reservation the placement allocates from.
    - `networkId` string, required — The network the placement belongs to.
    - `readyHostCount` integer — Number of hosts whose Region server resources are ready.

## Other responses

- `400` — Request body failed schema validation, or the request does not contain all the required fields.
- `401` — Authentication failed or the access token has expired.
- `403` — 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.
- `500` — 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.

---

[API](https://skmtc.net/nscale/apis/region-service-api.md) · [All operations](https://skmtc.net/nscale/apis/region-service-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nscale/region-service-api/revisions/c2991b23da6e/schema)