> ## Documentation Index > Fetch the complete documentation index at: https://docs.sfcompute.com/llms.txt > Use this file to discover all available pages before exploring further. # List deployments > > ⚠️ This endpoint is in [public preview](/preview/roadmap). List all deployments. ## OpenAPI ````yaml /preview/openapi.json get /preview/v2/deployments openapi: 3.1.0 info: title: sfc-api description: >- Public preview API - subject to change. See https://docs.sfcompute.com/preview/roadmap for details. version: 0.1.0 servers: - url: https://api.sfcompute.com security: - bearer_auth: [] tags: - name: Account description: The authenticated account and logged-in user. - name: Pools description: A bucket of owned compute balance over time. - name: Orders description: >- Place orders targeting a capacity to increase your reserved compute balance during some time period. - name: Instance Templates description: Reusable instance configuration. - name: Images description: Custom machine images for instances. - name: Roles description: TOML-based permission role definitions. - name: Grants description: Bind principals (users or tokens) to roles on a workspace. - name: Tokens description: Workspace-scoped API tokens. - name: Instances description: Spin up instances in a capacity to use your available compute. - name: Instance SKU Catalog description: Browse available instance SKU property definitions. - name: Procurements description: Market automations that maintain capacity by placing buy/sell orders. - name: Deployments description: >- Deployment automations that maintain a fleet of instances, including spot deployments that buy capacity up to a maximum price. - name: Users description: Read-only access to users within the caller's organization. - name: Workspaces description: Resource containers scoped to an account. - name: Permissions description: Inspect what the caller is allowed to do. - name: Billing description: Billing profile, contacts, and auto top-up settings. - name: Orderbook description: >- Read-only orderbook visibility: bid/ask spread, depth, open and filled orders, and historical fills, keyed on hardware requirements + delivery window. - name: Orders description: >- Estimate an order before placing it: filled price, fee, and operational notices. paths: /preview/v2/deployments: get: tags: - Deployments summary: List deployments description: |- > ⚠️ This endpoint is in [public preview](/preview/roadmap). List all deployments. operationId: list_deployments parameters: - name: workspace in: query description: Filter by workspace. required: true schema: $ref: '#/components/schemas/ResourcePathOrId_WorkspaceId' - name: pool in: query description: Filter by pool. required: false schema: $ref: '#/components/schemas/ResourcePathOrId_PoolId' - name: limit in: query required: false schema: type: integer format: u-int32 default: 50 maximum: 50 minimum: 1 - name: starting_after in: query required: false schema: $ref: '#/components/schemas/DeploymentsCursor' - name: ending_before in: query required: false schema: $ref: '#/components/schemas/DeploymentsCursor' responses: '200': description: Paginated list of deployments. content: application/json: schema: $ref: '#/components/schemas/ListDeploymentsResponse' '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '422': description: Validation failed. content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntityError' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/InternalServerError' components: schemas: ResourcePathOrId_WorkspaceId: type: string description: >- A resource path like 'sfc:workspace:acme:my-workspace' _or_ an ID. Resource paths are human-readable but not stable - they change when resources are renamed or moved. IDs are stable and permanent. examples: - wksp_k3R-nX9vLm7Qp2Yw5Jd8F pattern: >- (wksp_[0-9a-zA-Z_-]{1,21})|(sfc:workspace:[a-zA-Z0-9._-]+(:[a-zA-Z0-9._-]+){1,1}) ResourcePathOrId_PoolId: type: string description: >- A resource path like 'sfc:pool:acme:prod:my-pool' _or_ an ID. Resource paths are human-readable but not stable - they change when resources are renamed or moved. IDs are stable and permanent. examples: - pool_k3R-nX9vLm7Qp2Yw5Jd8F pattern: >- (pool_[0-9a-zA-Z_-]{1,21})|(sfc:pool:[a-zA-Z0-9._-]+(:[a-zA-Z0-9._-]+){2,2}) DeploymentsCursor: type: string examples: - deplc_gqXR7s0Kj5mHvE2wNpLc4Q pattern: ^deplc_[A-Za-z0-9_-]+$ ListDeploymentsResponse: type: object required: - object - has_more - data properties: object: type: string const: list default: list readOnly: true cursor: oneOf: - type: 'null' - $ref: '#/components/schemas/DeploymentsCursor' has_more: type: boolean data: type: array items: $ref: '#/components/schemas/DeploymentResource' UnauthorizedError: type: object required: - error properties: error: type: object required: - type - message properties: type: type: string const: authentication_error default: authentication_error readOnly: true message: type: string x-speakeasy-error-message: true ForbiddenError: type: object required: - error properties: error: type: object required: - type - message properties: type: type: string const: forbidden default: forbidden readOnly: true message: type: string x-speakeasy-error-message: true UnprocessableEntityError: type: object required: - error properties: error: type: object required: - type - message properties: type: type: string const: unprocessable_entity default: unprocessable_entity readOnly: true message: type: string x-speakeasy-error-message: true details: type: array items: $ref: '#/components/schemas/ErrorDetail' InternalServerError: type: object required: - error properties: error: type: object required: - type - message properties: type: type: string const: api_error default: api_error readOnly: true message: type: string x-speakeasy-error-message: true DeploymentResource: oneOf: - $ref: '#/components/schemas/DeploymentResponse' - $ref: '#/components/schemas/SpotDeploymentResponse' discriminator: propertyName: object mapping: deployment: '#/components/schemas/sfc-api_DeploymentResponse' spot_deployment: '#/components/schemas/sfc-api_SpotDeploymentResponse' ErrorDetail: type: object required: - code - message properties: field: type: - string - 'null' description: The field that caused the error (for validation errors) code: type: string description: Specific error code for this detail message: type: string description: Human-readable error message DeploymentResponse: allOf: - $ref: '#/components/schemas/DeploymentScope' - type: object required: - object - capacity - pool - instance_sku - instance_template - enabled - target_instance_count - instance_name_template - status - created_at - updated_at properties: object: type: string const: deployment default: deployment readOnly: true capacity: $ref: '#/components/schemas/CapacitySummary' description: Deprecated — use `pool`. pool: $ref: '#/components/schemas/PoolSummary' instance_sku: $ref: '#/components/schemas/InstanceSkuSummary' instance_template: $ref: '#/components/schemas/InstanceTemplateSummary' enabled: type: boolean target_instance_count: type: integer format: int32 instance_name_template: $ref: '#/components/schemas/NameTemplate' status: $ref: '#/components/schemas/ReconciliationStatus' created_at: $ref: '#/components/schemas/UnixEpoch' updated_at: $ref: '#/components/schemas/UnixEpoch' SpotDeploymentResponse: allOf: - $ref: '#/components/schemas/SpotDeploymentScope' - type: object required: - object - pool - instance_template - instance_sku - enabled - target_instance_count - max_buy_price_dollars_per_node_hour - instance_name_template - status - created_at - updated_at properties: object: type: string const: spot_deployment default: spot_deployment readOnly: true pool: $ref: '#/components/schemas/PoolSummary' instance_template: $ref: '#/components/schemas/InstanceTemplateSummary' instance_sku: $ref: '#/components/schemas/InstanceSkuSummary' description: Instance SKU this spot deployment's orders are pinned to. enabled: type: boolean target_instance_count: type: integer format: int32 max_buy_price_dollars_per_node_hour: $ref: '#/components/schemas/DollarsPerNodeHour' instance_name_template: $ref: '#/components/schemas/NameTemplate' status: $ref: '#/components/schemas/ReconciliationStatus' created_at: $ref: '#/components/schemas/UnixEpoch' updated_at: $ref: '#/components/schemas/UnixEpoch' description: >- A spot deployment buys compute up to a maximum price and runs instances on the secured pool. DeploymentScope: type: object required: - id - resource_path - owner - workspace - workspace_id - name properties: id: $ref: '#/components/schemas/DeploymentId' resource_path: $ref: '#/components/schemas/deploymentResourcePath_DeploymentId' owner: $ref: '#/components/schemas/Name' workspace: $ref: '#/components/schemas/Name' workspace_id: $ref: '#/components/schemas/WorkspaceId' name: $ref: '#/components/schemas/Name' CapacitySummary: type: object required: - id - name properties: id: $ref: '#/components/schemas/CapacityId' name: $ref: '#/components/schemas/Name' PoolSummary: type: object description: A pool referenced by id and name. required: - id - name properties: id: $ref: '#/components/schemas/PoolId' name: $ref: '#/components/schemas/Name' InstanceSkuSummary: type: object description: >- A summary of an instance SKU - its `id` and human-recognizable `alias` - embedded on resources that reference a SKU. required: - object - id - alias properties: object: type: string const: instance_sku default: instance_sku readOnly: true id: $ref: '#/components/schemas/InstanceSkuId' alias: $ref: '#/components/schemas/Name' InstanceTemplateSummary: type: object required: - id - name properties: id: $ref: '#/components/schemas/InstanceTemplateId' name: $ref: '#/components/schemas/Name' NameTemplate: type: string description: >- A name template using {{variable}} syntax. Available variables: {{adjective}} (~128 random adjectives), {{noun}} (~128 random nouns), {{nanoid(N)}} (N-character alphanumeric identifier, 1 ≤ N ≤ 21). The template must produce enough unique combinations to avoid collisions — equivalent to at least the default template {{adjective}}-{{noun}}-{{nanoid(6)}} (~1 quadrillion possibilities). Must start with an alphanumeric character. Resolved names are limited to 255 characters. examples: - my-fleet-{{nanoid(9)}} maxLength: 512 ReconciliationStatus: type: object required: - state - message properties: state: $ref: '#/components/schemas/AutomationStatus' message: type: string UnixEpoch: type: integer format: int64 description: Unix timestamp. example: 1738972800 SpotDeploymentScope: type: object required: - id - resource_path - owner - workspace - workspace_id - name properties: id: $ref: '#/components/schemas/SpotDeploymentId' resource_path: $ref: '#/components/schemas/spot_deploymentResourcePath_SpotDeploymentId' owner: $ref: '#/components/schemas/Name' workspace: $ref: '#/components/schemas/Name' workspace_id: $ref: '#/components/schemas/WorkspaceId' name: $ref: '#/components/schemas/Name' DollarsPerNodeHour: type: string description: >- Price in dollars per node-hour, encoded as a decimal string. Prices are rounded to the nearest $0.000060/node-hour market tick. This is one microdollar per node-minute. Responses contain the rounded value with six decimal places. Inputs must contain a decimal point, be non-negative, and not exceed $500/node-hour. examples: - '1.500000' pattern: ^\d+\.\d+$ DeploymentId: type: string examples: - depl_k3R-nX9vLm7Qp2Yw5Jd8F pattern: depl_[0-9a-zA-Z_-]{1,21} deploymentResourcePath_DeploymentId: type: string description: >- A resource path for a deployment resource. Format: sfc:deployment:::. examples: - sfc:deployment::: pattern: sfc:deployment:([a-zA-Z0-9._-]+:){2}[a-zA-Z0-9._-]+ Name: type: string examples: - my-resource-name maxLength: 255 minLength: 1 pattern: '[a-zA-Z0-9][a-zA-Z0-9._-]{0,254}' WorkspaceId: type: string examples: - wksp_k3R-nX9vLm7Qp2Yw5Jd8F pattern: wksp_[0-9a-zA-Z_-]{1,21} CapacityId: oneOf: - type: string examples: - cap_k3R-nX9vLm7Qp2Yw5Jd8F pattern: cap_[0-9a-zA-Z_-]{1,21} - type: string description: Legacy alias prefix; accepted on read, never emitted on write. pattern: pool_[0-9a-zA-Z_-]{1,21} description: >- Accepts the canonical prefix below; additional legacy prefixes are aliased for read compatibility. Writes always emit the canonical form. PoolId: type: string examples: - pool_k3R-nX9vLm7Qp2Yw5Jd8F pattern: pool_[0-9a-zA-Z_-]{1,21} InstanceSkuId: oneOf: - type: string examples: - isku_k3R-nX9vLm7Qp2Yw5Jd8F pattern: isku_[0-9a-zA-Z_-]{1,21} - type: string description: Legacy alias prefix; accepted on read, never emitted on write. pattern: clus_[0-9a-zA-Z_-]{1,21} description: >- Accepts the canonical prefix below; additional legacy prefixes are aliased for read compatibility. Writes always emit the canonical form. InstanceTemplateId: oneOf: - type: string examples: - itmpl_k3R-nX9vLm7Qp2Yw5Jd8F pattern: itmpl_[0-9a-zA-Z_-]{1,21} - type: string description: Legacy alias prefix; accepted on read, never emitted on write. pattern: ntmpl_[0-9a-zA-Z_-]{1,21} description: >- Accepts the canonical prefix below; additional legacy prefixes are aliased for read compatibility. Writes always emit the canonical form. AutomationStatus: type: string enum: - info - warning - error SpotDeploymentId: type: string examples: - spot_k3R-nX9vLm7Qp2Yw5Jd8F pattern: spot_[0-9a-zA-Z_-]{1,21} spot_deploymentResourcePath_SpotDeploymentId: type: string description: >- A resource path for a spot_deployment resource. Format: sfc:spot_deployment:::. examples: - sfc:spot_deployment::: pattern: sfc:spot_deployment:([a-zA-Z0-9._-]+:){2}[a-zA-Z0-9._-]+ securitySchemes: bearer_auth: type: http scheme: bearer bearerFormat: JWT description: >- Create an API token using `sf tokens create` or at https://sfcompute.com/account/api-keys. ````