---
title: "List orders"
method: GET
path: "/preview/v2/orders"
tags: ["Orders"]
---

# List orders

`GET /preview/v2/orders`

> ⚠️ This endpoint is in [public preview](/preview/roadmap).

List all orders.

## Query parameters

- `id` OrderId[]
- `pool` string — 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.
- `workspace` string — 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.
- `side` 'sell' | 'buy'
- `status` OrderStatus[]
- `created_after` integer — Unix timestamp.
- `created_before` integer — Unix timestamp.
- `procurement` string — 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.
- `sort_by` 'created_at' | '-created_at' | 'start_at' | '-start_at'
- `limit` integer
- `starting_after` string
- `ending_before` string

## Response `200`

Paginated list of orders.

- V2ListOrdersResponse
  - `object` 'list', required
  - `cursor` string
  - `has_more` boolean, required
  - `data` V2OrderResponse[], required
    - `object` 'order', required
    - `id` string, required
    - `capacity` CapacitySummary, required
      - `id` union, required — Accepts the canonical prefix below; additional legacy prefixes are aliased for read compatibility. Writes always emit the canonical form.
        - string
        - string — Legacy alias prefix; accepted on read, never emitted on write.
      - `name` string, required
    - `pool` PoolSummary, required — A pool referenced by id and name.
      - `id` string, required
      - `name` string, required
    - `side` 'sell' | 'buy', required
    - `allow_standing` boolean, required — 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` boolean — If true, the order may fill partially — fewer nodes and/or a subset of the requested time window.
    - `instance_sku` InstanceSkuSummary, required — A summary of an instance SKU - its `id` and human-recognizable `alias` - embedded on resources that reference a SKU.
      - `object` 'instance_sku', required
      - `id` union, required — Accepts the canonical prefix below; additional legacy prefixes are aliased for read compatibility. Writes always emit the canonical form.
        - string
        - string — Legacy alias prefix; accepted on read, never emitted on write.
      - `alias` string, required
    - `allocation_schedule_delta` ScheduleEntry[], required — 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`.
      - `start_at` integer, required — Unix timestamp.
      - `end_at` integer — Unix timestamp.
      - `node_count` integer, required
    - `filled_allocation_schedule_delta` ScheduleEntry[], required — 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`.
      - `start_at` integer, required — Unix timestamp.
      - `end_at` integer — Unix timestamp.
      - `node_count` integer, required
    - `limit_price_dollars_per_node_hour` string, required — 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.
    - `status` 'pending' | 'filled' | 'partially_filled' | 'rejected' | 'cancelled' | 'standing', required — 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.
    - `created_at` integer, required — Unix timestamp.
    - `created_by` V2OrderPrincipal — 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.
      - `id` string, required — `users.id` for a user principal, `api_tokens.id` for a token principal.
      - `type` 'user' | 'token', required — Whether an order's `created_by` principal is a human user or an API token.
      - `email` string, nullable — Email of the user, when the principal is a user with a recorded email.
      - `name` string, nullable — Name of the API token, when the principal is a token.
    - `filled_at` integer — Unix timestamp.
    - `filled_average_price_dollars_per_node_hour` string — 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.
    - `fills` V2OrderFill[] — Each contract produced by this order. Empty for unfilled orders.
      - `contract` string
      - `filled_at` integer, required — Unix timestamp.
      - `allocation_schedule_delta` ScheduleEntry[], required — 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`.
        - `start_at` integer, required — Unix timestamp.
        - `end_at` integer — Unix timestamp.
        - `node_count` integer, required
      - `price_dollars_per_node_hour` string, required — 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.
    - `cancelled_at` integer — Unix timestamp.

## Other responses

- `401` — Unauthorized.
- `403` — Forbidden.
- `422` — Validation failed.
- `500` — Internal server error.

---

[API](https://skmtc.dev/sfcompute/apis/sfc-api.md) · [All operations](https://skmtc.dev/sfcompute/apis/sfc-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/sfcompute/sfc-api/revisions/f3ff1539c0d9/schema)