Estimate an order - San Francisco Compute Docs

Estimate an order

curl --request POST \
  --url https://api.sfcompute.com/preview/v2/order_preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "requirements": {
    "accelerator": [
      "H100"
    ]
  },
  "start_at": 1738972800,
  "duration_seconds": 1,
  "node_count": 123,
  "side": "buy",
  "pool": "pool_k3R-nX9vLm7Qp2Yw5Jd8F",
  "allow_partial": true,
  "limit_price_dollars_per_node_hour": "18.000000"
}
'

import requests

url = "https://api.sfcompute.com/preview/v2/order_preview"

payload = {
    "requirements": { "accelerator": ["H100"] },
    "start_at": 1738972800,
    "duration_seconds": 1,
    "node_count": 123,
    "side": "buy",
    "pool": "pool_k3R-nX9vLm7Qp2Yw5Jd8F",
    "allow_partial": True,
    "limit_price_dollars_per_node_hour": "18.000000"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    requirements: {accelerator: ['H100']},
    start_at: 1738972800,
    duration_seconds: 1,
    node_count: 123,
    side: 'buy',
    pool: 'pool_k3R-nX9vLm7Qp2Yw5Jd8F',
    allow_partial: true,
    limit_price_dollars_per_node_hour: '18.000000'
  })
};

fetch('https://api.sfcompute.com/preview/v2/order_preview', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sfcompute.com/preview/v2/order_preview",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'requirements' => [
        'accelerator' => [
                'H100'
        ]
    ],
    'start_at' => 1738972800,
    'duration_seconds' => 1,
    'node_count' => 123,
    'side' => 'buy',
    'pool' => 'pool_k3R-nX9vLm7Qp2Yw5Jd8F',
    'allow_partial' => true,
    'limit_price_dollars_per_node_hour' => '18.000000'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sfcompute.com/preview/v2/order_preview"

	payload := strings.NewReader("{\n  \"requirements\": {\n    \"accelerator\": [\n      \"H100\"\n    ]\n  },\n  \"start_at\": 1738972800,\n  \"duration_seconds\": 1,\n  \"node_count\": 123,\n  \"side\": \"buy\",\n  \"pool\": \"pool_k3R-nX9vLm7Qp2Yw5Jd8F\",\n  \"allow_partial\": true,\n  \"limit_price_dollars_per_node_hour\": \"18.000000\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sfcompute.com/preview/v2/order_preview")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"requirements\": {\n    \"accelerator\": [\n      \"H100\"\n    ]\n  },\n  \"start_at\": 1738972800,\n  \"duration_seconds\": 1,\n  \"node_count\": 123,\n  \"side\": \"buy\",\n  \"pool\": \"pool_k3R-nX9vLm7Qp2Yw5Jd8F\",\n  \"allow_partial\": true,\n  \"limit_price_dollars_per_node_hour\": \"18.000000\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sfcompute.com/preview/v2/order_preview")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"requirements\": {\n    \"accelerator\": [\n      \"H100\"\n    ]\n  },\n  \"start_at\": 1738972800,\n  \"duration_seconds\": 1,\n  \"node_count\": 123,\n  \"side\": \"buy\",\n  \"pool\": \"pool_k3R-nX9vLm7Qp2Yw5Jd8F\",\n  \"allow_partial\": true,\n  \"limit_price_dollars_per_node_hour\": \"18.000000\"\n}"

response = http.request(request)
puts response.read_body

{
  "post_order_body": {
    "pool": "pool_k3R-nX9vLm7Qp2Yw5Jd8F",
    "side": "sell",
    "instance_sku": "isku_k3R-nX9vLm7Qp2Yw5Jd8F",
    "allocation_schedule_delta": [
      {
        "start_at": 1738972800,
        "node_count": 123,
        "end_at": 1738972800
      }
    ],
    "limit_price_dollars_per_node_hour": "18.000000",
    "allow_standing": true,
    "allow_partial": true
  },
  "fee": {
    "flat_dollars_per_node_hour": "18.000000",
    "percentage_bps": 123
  },
  "type": "quoted",
  "matched_node_minutes": 123,
  "matched_allocation_schedule": [
    {
      "start_at": 1738972800,
      "node_count": 123,
      "end_at": 1738972800
    }
  ],
  "notices": [
    {
      "start_at": 1738972800,
      "end_at": 1738972800,
      "maintenance_type": "info",
      "title": "<string>",
      "description": "<string>",
      "type": "maintenance_window",
      "action_message": "<string>"
    }
  ]
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>"
  }
}

{
  "error": {
    "type": "unprocessable_entity",
    "message": "<string>",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "api_error",
    "message": "<string>"
  }
}

POST

preview

order_preview

Estimate an order

curl --request POST \
  --url https://api.sfcompute.com/preview/v2/order_preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "requirements": {
    "accelerator": [
      "H100"
    ]
  },
  "start_at": 1738972800,
  "duration_seconds": 1,
  "node_count": 123,
  "side": "buy",
  "pool": "pool_k3R-nX9vLm7Qp2Yw5Jd8F",
  "allow_partial": true,
  "limit_price_dollars_per_node_hour": "18.000000"
}
'

import requests

url = "https://api.sfcompute.com/preview/v2/order_preview"

payload = {
    "requirements": { "accelerator": ["H100"] },
    "start_at": 1738972800,
    "duration_seconds": 1,
    "node_count": 123,
    "side": "buy",
    "pool": "pool_k3R-nX9vLm7Qp2Yw5Jd8F",
    "allow_partial": True,
    "limit_price_dollars_per_node_hour": "18.000000"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    requirements: {accelerator: ['H100']},
    start_at: 1738972800,
    duration_seconds: 1,
    node_count: 123,
    side: 'buy',
    pool: 'pool_k3R-nX9vLm7Qp2Yw5Jd8F',
    allow_partial: true,
    limit_price_dollars_per_node_hour: '18.000000'
  })
};

fetch('https://api.sfcompute.com/preview/v2/order_preview', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sfcompute.com/preview/v2/order_preview",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'requirements' => [
        'accelerator' => [
                'H100'
        ]
    ],
    'start_at' => 1738972800,
    'duration_seconds' => 1,
    'node_count' => 123,
    'side' => 'buy',
    'pool' => 'pool_k3R-nX9vLm7Qp2Yw5Jd8F',
    'allow_partial' => true,
    'limit_price_dollars_per_node_hour' => '18.000000'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sfcompute.com/preview/v2/order_preview"

	payload := strings.NewReader("{\n  \"requirements\": {\n    \"accelerator\": [\n      \"H100\"\n    ]\n  },\n  \"start_at\": 1738972800,\n  \"duration_seconds\": 1,\n  \"node_count\": 123,\n  \"side\": \"buy\",\n  \"pool\": \"pool_k3R-nX9vLm7Qp2Yw5Jd8F\",\n  \"allow_partial\": true,\n  \"limit_price_dollars_per_node_hour\": \"18.000000\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sfcompute.com/preview/v2/order_preview")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"requirements\": {\n    \"accelerator\": [\n      \"H100\"\n    ]\n  },\n  \"start_at\": 1738972800,\n  \"duration_seconds\": 1,\n  \"node_count\": 123,\n  \"side\": \"buy\",\n  \"pool\": \"pool_k3R-nX9vLm7Qp2Yw5Jd8F\",\n  \"allow_partial\": true,\n  \"limit_price_dollars_per_node_hour\": \"18.000000\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sfcompute.com/preview/v2/order_preview")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"requirements\": {\n    \"accelerator\": [\n      \"H100\"\n    ]\n  },\n  \"start_at\": 1738972800,\n  \"duration_seconds\": 1,\n  \"node_count\": 123,\n  \"side\": \"buy\",\n  \"pool\": \"pool_k3R-nX9vLm7Qp2Yw5Jd8F\",\n  \"allow_partial\": true,\n  \"limit_price_dollars_per_node_hour\": \"18.000000\"\n}"

response = http.request(request)
puts response.read_body

{
  "post_order_body": {
    "pool": "pool_k3R-nX9vLm7Qp2Yw5Jd8F",
    "side": "sell",
    "instance_sku": "isku_k3R-nX9vLm7Qp2Yw5Jd8F",
    "allocation_schedule_delta": [
      {
        "start_at": 1738972800,
        "node_count": 123,
        "end_at": 1738972800
      }
    ],
    "limit_price_dollars_per_node_hour": "18.000000",
    "allow_standing": true,
    "allow_partial": true
  },
  "fee": {
    "flat_dollars_per_node_hour": "18.000000",
    "percentage_bps": 123
  },
  "type": "quoted",
  "matched_node_minutes": 123,
  "matched_allocation_schedule": [
    {
      "start_at": 1738972800,
      "node_count": 123,
      "end_at": 1738972800
    }
  ],
  "notices": [
    {
      "start_at": 1738972800,
      "end_at": 1738972800,
      "maintenance_type": "info",
      "title": "<string>",
      "description": "<string>",
      "type": "maintenance_window",
      "action_message": "<string>"
    }
  ]
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>"
  }
}

{
  "error": {
    "type": "unprocessable_entity",
    "message": "<string>",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "api_error",
    "message": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Create an API token using sf tokens create or at https://sfcompute.com/dashboard/tokens.

Body

application/json

Option 1
Option 2

requirements

object

required

Key/value filters on instance SKU properties.

Keys are the property names instance SKUs carry on GET /v2/instance_skus (e.g. accelerator); values match each property's value spelling. The reserved instance_sku key pins to a single SKU by id.

Empty map = no constraints.

Show child attributes

Example:

{ "accelerator": ["H100"] }

start_at

integer<int64>

required

Order start: a time on the allocation schedule grid, or the current time.

Example:

1738972800

duration_seconds

integer<u-int64>

required

Order duration in seconds, a multiple of 60. The order must end on the allocation schedule grid.

Required range: x >= 0

node_count

integer<int32>

required

Number of nodes. Must be positive.

side

string

default:buy

required

Allowed value: "buy"

pool

null | string

Pool that receives compute when the order fills. Omit to get an estimate without pinning to a pool. The response body then returns a placeholder you must replace before submitting to /v2/orders.

Pattern: (pool_[0-9a-zA-Z_-]{1,21})|(sfc:pool:[a-zA-Z0-9._-]+(:[a-zA-Z0-9._-]+){2,2})

Example:

"pool_k3R-nX9vLm7Qp2Yw5Jd8F"

allow_partial

boolean

If true, the estimate models an order that may fill partially — fewer nodes and/or a subset of the requested time window — instead of one that fills completely or not at all. Send the same value you will send as allow_partial on POST /v2/orders, or the estimate answers for a different order than the one you place. Absent means all-or-nothing.

limit_price_dollars_per_node_hour

null | string

The most you will pay. The estimate models a buy limited to this rate instead of one that takes any price, so it answers what an order at this limit would fill: the matched part's average rate stays at or under it, and when nothing can match within it, the response is unavailable with reason no_availability. The quoted rate never exceeds this value. Absent means any price.

Pattern: ^\d+\.\d+$

Example:

"18.000000"

Response

Estimate result.

Option 1
Option 2

post_order_body

object

required

Ready-to-submit body for POST /v2/orders, priced at the estimated rate. It is an estimate, not a promise to fill: the market can move before you post it, and when the match combines resting orders at different prices, posting it verbatim can fill less than estimated or nothing at all. For an allow_partial estimate that matched only part of the order, the price is the rate over the part that matched.

Show child attributes

fee

object

required

Fee policy for the matched instance SKU.

Show child attributes

type

string

default:quoted

required

Allowed value: "quoted"

matched_node_minutes

integer<int64> | null

Node-minutes the quoted rate was derived over, present only when the estimate matched part of the order rather than all of it. To estimate the execution total, multiply the rate by this area in node-hours (matched_node_minutes / 60), not by the full allocation_schedule_delta rectangle.

When absent, the whole order matched and the rectangle is the area to price. For a buy the product can overstate the execution total: its rate is derived over the order's remaining window less one minute, so it still clears if placement lands a minute later, and is capped at limit_price_dollars_per_node_hour when one is sent.

A partial quote's rate is rounded down for a sell and up for a buy, which puts the product within $0.000001 per matched node-minute of the exact total.

Treat this area as an estimate rather than a guarantee: when the match combines resting orders at different prices, posting the quoted rate as a limit may fill less than this.

matched_allocation_schedule

null | object[]

The allocation the estimate actually matched. It can be smaller than the requested schedule: an allow_partial estimate may match fewer nodes or less time, and an order that starts now cannot fill the minute already under way. Like the rate, it is an estimate, not a promise to fill.

Show child attributes

notices

object[]

Maintenance windows for the matched instance SKU overlapping the order's delivery window.

Option 1
Option 2

Show child attributes