> ## 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 orders > > ⚠️ This endpoint is in [public preview](/preview/roadmap). List all orders. ## OpenAPI ````yaml /preview/openapi.json get /preview/v2/orders 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/orders: get: tags: - Orders summary: List orders description: |- > ⚠️ This endpoint is in [public preview](/preview/roadmap). List all orders. operationId: list_orders parameters: - name: id in: query description: Filter by order ID (repeatable). required: false schema: type: array items: $ref: '#/components/schemas/OrderId' style: form explode: true - name: pool in: query description: Filter by pool. required: false schema: $ref: '#/components/schemas/ResourcePathOrId_PoolId' - name: workspace in: query description: >- Scope the listing to a single workspace (ID, resource path, or name). Ignored when `pool` is given (the pool already names its workspace). Without either, the list spans the whole organization and requires an org-level `Order:List` grant. required: false schema: $ref: '#/components/schemas/ResourcePathOrId_WorkspaceId' - name: side in: query required: false schema: $ref: '#/components/schemas/Side' - name: status in: query description: Filter by status (repeatable). required: false schema: type: array items: $ref: '#/components/schemas/OrderStatus' style: form explode: true - name: created_after in: query required: false schema: $ref: '#/components/schemas/UnixEpoch' - name: created_before in: query required: false schema: $ref: '#/components/schemas/UnixEpoch' - name: procurement in: query description: >- Filter to one procurement's orders (ID or resource path). Without it, the list omits procurement orders. required: false schema: $ref: '#/components/schemas/ResourcePathOrId_ProcurementId' - name: deployment in: query description: >- Filter to one deployment's orders (ID or resource path). Without it, the list omits deployment-managed orders. required: false schema: $ref: '#/components/schemas/DeploymentReference' - name: sort_by in: query description: Prefix with `-` for descending. required: false schema: oneOf: - $ref: '#/components/schemas/v2.OrderSortBy' default: '-created_at' - name: limit in: query required: false schema: type: integer format: u-int32 default: 50 maximum: 200 minimum: 1 - name: starting_after in: query description: Set to the response's `cursor` to fetch the next page. required: false schema: $ref: '#/components/schemas/OrdersCursor' - name: ending_before in: query description: Set to the response's `cursor` to fetch the previous page. required: false schema: $ref: '#/components/schemas/OrdersCursor' responses: '200': description: Paginated list of orders. content: application/json: schema: $ref: '#/components/schemas/v2.ListOrdersResponse' '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: OrderId: type: string examples: - ordr_k3R-nX9vLm7Qp2Yw5Jd8F pattern: ordr_[0-9a-zA-Z_-]{1,21} 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}) 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}) Side: type: string enum: - sell - buy OrderStatus: type: string description: >- The status of an order in the system. `pending` = not resolved/processed yet. `filled` = order executed. `partially_filled` = the order matched part of its requested capacity and remains active for the remainder. `standing` = the order is waiting for a match. `cancelled` = the order was cancelled either automatically (not a standing order and didn't immediately fill, or current time past `end_at`) or by explicit cancellation. `rejected` = validation/system error occurred. enum: - pending - filled - partially_filled - rejected - cancelled - standing UnixEpoch: type: integer format: int64 description: Unix timestamp. example: 1738972800 ResourcePathOrId_ProcurementId: type: string description: >- A resource path like 'sfc:procurement:acme:prod:my-procurement' _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: - proc_k3R-nX9vLm7Qp2Yw5Jd8F pattern: >- (proc_[0-9a-zA-Z_-]{1,21})|(sfc:procurement:[a-zA-Z0-9._-]+(:[a-zA-Z0-9._-]+){2,2}) DeploymentReference: oneOf: - $ref: '#/components/schemas/ResourcePathOrId_DeploymentId' - $ref: '#/components/schemas/ResourcePathOrId_SpotDeploymentId' v2.OrderSortBy: type: string enum: - created_at - '-created_at' - start_at - '-start_at' OrdersCursor: type: string examples: - ordrc_gqXR7s0Kj5mHvE2wNpLc4Q pattern: ^ordrc_[A-Za-z0-9_-]+$ v2.ListOrdersResponse: type: object required: - object - has_more - data properties: object: type: string const: list default: list readOnly: true cursor: oneOf: - type: 'null' - $ref: '#/components/schemas/OrdersCursor' description: Pass as `starting_after` or `ending_before` to paginate. has_more: type: boolean data: type: array items: $ref: '#/components/schemas/v2.OrderResponse' 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 ResourcePathOrId_DeploymentId: type: string description: >- A resource path like 'sfc:deployment:acme:prod:my-deployment' _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: - depl_k3R-nX9vLm7Qp2Yw5Jd8F pattern: >- (depl_[0-9a-zA-Z_-]{1,21})|(sfc:deployment:[a-zA-Z0-9._-]+(:[a-zA-Z0-9._-]+){2,2}) ResourcePathOrId_SpotDeploymentId: type: string description: >- A resource path like 'sfc:spot_deployment:acme:prod:my-spot_deployment' _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: - spot_k3R-nX9vLm7Qp2Yw5Jd8F pattern: >- (spot_[0-9a-zA-Z_-]{1,21})|(sfc:spot_deployment:[a-zA-Z0-9._-]+(:[a-zA-Z0-9._-]+){2,2}) v2.OrderResponse: type: object required: - object - id - capacity - pool - side - allow_standing - instance_sku - allocation_schedule_delta - filled_allocation_schedule_delta - limit_price_dollars_per_node_hour - status - created_at properties: object: type: string const: order default: order readOnly: true id: $ref: '#/components/schemas/OrderId' capacity: $ref: '#/components/schemas/CapacitySummary' description: >- Deprecated — use `pool`. Target pool that receives or loses compute if this order fills (depending on order type). pool: $ref: '#/components/schemas/PoolSummary' side: $ref: '#/components/schemas/Side' allow_standing: type: boolean description: >- If true, the order stays in the order book until either fills, is explicitly cancelled, or the order end time is reached resulting in automatic cancellation. If false, the order is cancelled immediately if it doesn't fill. allow_partial: type: boolean description: >- If true, the order may fill partially — fewer nodes and/or a subset of the requested time window. instance_sku: $ref: '#/components/schemas/InstanceSkuSummary' description: >- Instance SKU this order is pinned to. Carries the SKU's human-readable name when one is registered. allocation_schedule_delta: $ref: '#/components/schemas/Schedule' description: >- Change in capacity if the order fills. Must be a single time range with both `start_at` and `end_at`. filled_allocation_schedule_delta: $ref: '#/components/schemas/Schedule' description: >- The portion of the requested schedule that has filled so far. Empty for orders with no fills yet; the unfilled remainder is `allocation_schedule_delta` minus this. limit_price_dollars_per_node_hour: $ref: '#/components/schemas/DollarsPerNodeHour' status: $ref: '#/components/schemas/OrderStatus' created_at: $ref: '#/components/schemas/UnixEpoch' created_by: oneOf: - type: 'null' - $ref: '#/components/schemas/v2.OrderPrincipal' description: >- Principal that placed the order — the human user when known, otherwise the API token that placed it. `null` for orders that predate attribution. Always present (value-or-null) like other order attributes, since every order conceptually has a creator. filled_at: oneOf: - type: 'null' - $ref: '#/components/schemas/UnixEpoch' filled_average_price_dollars_per_node_hour: oneOf: - type: 'null' - $ref: '#/components/schemas/DollarsPerNodeHour' fills: type: array items: $ref: '#/components/schemas/v2.OrderFill' description: Each contract produced by this order. Empty for unfilled orders. cancelled_at: oneOf: - type: 'null' - $ref: '#/components/schemas/UnixEpoch' 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 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' Schedule: type: array items: $ref: '#/components/schemas/ScheduleEntry' description: >- Node count over time, as a list of `[start_at, end_at)` time ranges. Example: 5 nodes from t=0 to t=3600 is `[{"start_at": 0, "end_at": 3600, "node_count": 5}]`. `start_at` and `end_at` must be 60-second aligned, `node_count` must be non-negative. On non-final entries, `end_at` may be omitted (inferred from the next entry's `start_at`); gaps fill with `node_count: 0`. 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+$ v2.OrderPrincipal: type: object description: >- The principal that placed an order. `type` distinguishes the two cases: a user carries `email` (when an email identity exists); a token carries `name`. The inapplicable field is omitted. required: - id - type properties: id: type: string description: >- `users.id` for a user principal, `api_tokens.id` for a token principal. type: $ref: '#/components/schemas/v2.OrderPrincipalKind' email: type: - string - 'null' description: >- Email of the user, when the principal is a user with a recorded email. name: type: - string - 'null' description: Name of the API token, when the principal is a token. v2.OrderFill: type: object description: >- A single fill event: one contract that was produced when the order matched. required: - filled_at - allocation_schedule_delta - price_dollars_per_node_hour properties: contract: oneOf: - type: 'null' - $ref: '#/components/schemas/ContractId' filled_at: $ref: '#/components/schemas/UnixEpoch' allocation_schedule_delta: $ref: '#/components/schemas/Schedule' description: >- Capacity change this fill delivered. Quantities are always positive; `side` on the parent order determines whether this added or removed capacity. price_dollars_per_node_hour: $ref: '#/components/schemas/DollarsPerNodeHour' 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. Name: type: string examples: - my-resource-name maxLength: 255 minLength: 1 pattern: '[a-zA-Z0-9][a-zA-Z0-9._-]{0,254}' 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. ScheduleEntry: type: object description: >- A `[start_at, end_at)` time range with a fixed `node_count`. `end_at` is `null` only on the final entry, marking an unbounded tail. required: - start_at - node_count properties: start_at: $ref: '#/components/schemas/UnixEpoch' end_at: oneOf: - type: 'null' - $ref: '#/components/schemas/UnixEpoch' node_count: type: integer format: int32 v2.OrderPrincipalKind: type: string description: >- Whether an order's `created_by` principal is a human user or an API token. enum: - user - token ContractId: type: string examples: - cont_k3R-nX9vLm7Qp2Yw5Jd8F pattern: cont_[0-9a-zA-Z_-]{1,21} 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. ````