> ## 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 market fills

> All contracts that filled on hardware meeting the requirements for the given delivery window, sorted newest first. One row per fill (contract). Participant identity is never exposed.



## OpenAPI

````yaml /preview/openapi.json get /preview/v2/orderbook/fills
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: 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 on a capacity.
  - 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 of book, 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/orderbook/fills:
    get:
      tags:
        - Orderbook
      summary: List market fills
      description: >-
        All contracts that filled on hardware meeting the requirements for the
        given delivery window, sorted newest first. One row per fill (contract).
        Participant identity is never exposed.
      operationId: list_orderbook_fills
      parameters:
        - name: requirements
          in: query
          description: URL-safe `field[:op]:value` triples joined by `;`.
          required: false
          schema:
            type: string
          example: accelerator:H100
        - name: start_at
          in: query
          description: Start of the delivery window.
          required: true
          schema:
            $ref: '#/components/schemas/UnixEpoch'
          example: 1746057600
        - name: end_at
          in: query
          description: End of the delivery window.
          required: true
          schema:
            $ref: '#/components/schemas/UnixEpoch'
          example: 1746662400
        - name: since_at
          in: query
          description: >-
            Lower bound on the contract's `created_at` (when the fill was
            recorded). Unix epoch seconds. Defaults to `now - 7d`; clamped to at
            most 90 days before `now` to bound scan cost.
          required: false
          schema:
            $ref: '#/components/schemas/UnixEpoch'
          example: 1745452800
        - name: limit
          in: query
          description: Maximum results to return. Clamped to [1, 200]. Default 50.
          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 (older) page.
          required: false
          schema:
            $ref: '#/components/schemas/OrderbookFillsCursor'
      responses:
        '200':
          description: Paginated list of fills.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOrderbookFillsResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '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:
    UnixEpoch:
      type: integer
      format: int64
      description: Unix timestamp.
      example: 1738972800
    OrderbookFillsCursor:
      type: string
      examples:
        - mfilc_gqXR7s0Kj5mHvE2wNpLc4Q
      pattern: ^mfilc_[A-Za-z0-9_-]+$
    ListOrderbookFillsResponse:
      type: object
      description: Paginated list of historical fills, newest first.
      required:
        - object
        - requirements
        - start_at
        - end_at
        - requested_at
        - has_more
        - data
      properties:
        object:
          type: string
          const: list
          default: list
          readOnly: true
        requirements:
          $ref: '#/components/schemas/Requirements'
        start_at:
          $ref: '#/components/schemas/UnixEpoch'
        end_at:
          $ref: '#/components/schemas/UnixEpoch'
        requested_at:
          $ref: '#/components/schemas/UnixEpoch'
          description: Server time when the fills were sampled.
        cursor:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/OrderbookFillsCursor'
              description: Pass as `starting_after` to fetch the next page.
        has_more:
          type: boolean
        data:
          type: array
          items:
            $ref: '#/components/schemas/OrderbookFill'
    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
    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
    Requirements:
      type: object
      description: >-
        Key/value filters on instance SKU properties.


        Valid keys and values are published at `GET
        /v2/instance_sku_property_catalog`.


        Empty map = no constraints.
      additionalProperties:
        type: array
        items:
          $ref: '#/components/schemas/Name'
      propertyNames:
        type: string
        examples:
          - my-resource-name
        maxLength: 255
        minLength: 1
        pattern: '[a-zA-Z0-9][a-zA-Z0-9._-]{0,254}'
      example:
        accelerator:
          - H100
    OrderbookFill:
      type: object
      description: >-
        A single trade: execution rate, delivered nodes over time, and the time
        it was recorded.
      required:
        - dollars_per_node_hour
        - allocation_schedule_delta
        - filled_at
      properties:
        dollars_per_node_hour:
          $ref: '#/components/schemas/DollarsPerNodeHour'
          description: Execution rate in dollars per node-hour.
        allocation_schedule_delta:
          $ref: '#/components/schemas/Schedule'
          description: >-
            Nodes delivered by this fill over time. Flat for a rectangular fill;
            piecewise when the delivered shape varies.
        filled_at:
          $ref: '#/components/schemas/UnixEpoch'
          description: When the fill was recorded.
    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
    Name:
      type: string
      examples:
        - my-resource-name
      maxLength: 255
      minLength: 1
      pattern: '[a-zA-Z0-9][a-zA-Z0-9._-]{0,254}'
    DollarsPerNodeHour:
      type: string
      description: Price rate in dollars per node-hour.
      examples:
        - '2.500000'
      pattern: ^\d+\.\d+$
    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`.
    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
  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.

````