Get sandbox usage

GET

sandboxes

{sandboxId}

usage

Get boat usage

curl --request GET \
  --url https://boat.dev/api/v1/sandboxes/{sandboxId}/usage \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://boat.dev/api/v1/sandboxes/{sandboxId}/usage', 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://boat.dev/api/v1/sandboxes/{sandboxId}/usage",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://boat.dev/api/v1/sandboxes/{sandboxId}/usage"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://boat.dev/api/v1/sandboxes/{sandboxId}/usage")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "ok": true,
  "type": "sandbox.usage",
  "sandboxId": "bx_23456789",
  "sandboxType": "default",
  "billingMultiplier": 1,
  "since": "2026-09-01T00:00:00.000Z",
  "until": "2026-09-14T09:30:00.000Z",
  "seconds": 4980,
  "dollars": 0.0498,
  "secondsPerDollar": 100000,
  "running": false
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 400,
  "code": "invalid_json",
  "message": "Request body must be valid JSON.",
  "error": {
    "code": "invalid_json",
    "message": "Request body must be valid JSON.",
    "status": 400
  },
  "requestId": "req_01HX..."
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 401,
  "code": "unauthorized",
  "message": "Unauthorized",
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized",
    "status": 401
  },
  "requestId": "req_01HX..."
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 409,
  "code": "provider_not_configured",
  "message": "Prompting is locked until Codex is configured on the Agents page.",
  "requestId": "req_01HX...",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

Boat bearer token in the form boat_.... Service API keys authenticate sandbox operations.

Path Parameters

sandboxId

string

required

Public Sandbox id returned by create/list/get sandbox calls.

Pattern: ^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$

Query Parameters

since

string

Count from this time, ISO 8601 or Unix epoch seconds. Default is the sandbox's creation.

until

string

Count up to this time, ISO 8601 or Unix epoch seconds. Default is now.

Response

Billable machine time for the sandbox inside the window.

boolean

required

Example:

true

type

string

required

Stable success envelope discriminator added by v1.

Example:

"sandbox.usage"

sandboxId

string

required

Pattern: ^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$

Example:

"bx_23456789"

sandboxType

enum<string>

required

The sandbox's current machine size, which sets billingMultiplier.

Available options:

small,

default,

large,

xlarge

billingMultiplier

number

required

Rate at which this sandbox consumes machine time. 0.5 for small, 1 for default, 2 for large, and 50/9 for xlarge.

Example:

1

since

string<date-time>

required

Start of the window the figures cover. The sandbox's creation time when the request did not pass since.

until

string<date-time>

required

End of the window. Now when the request did not pass until, or passed one in the future.

seconds

integer

required

Billable machine-seconds inside the window, the type multiplier already applied: a large sandbox that ran ten minutes reads 1200. Includes a running sandbox's time up to until. Time while stopped is never counted and time past a refused stop is excluded.

Example:

4980

dollars

number

required

seconds at list price (seconds / secondsPerDollar), whatever plan, trial or gift actually paid for it. Up to six decimals.

Example:

0.0498

secondsPerDollar

integer

required

How many billable seconds one dollar buys, so you can price seconds yourself.

Example:

100000

running

boolean

required

The meter is still moving: the sandbox is up and no refused stop is holding it paused. Read again after it stops for the final figure. false on a sandbox that is up but paused past a refused stop, whose figure will not change until it is used again.

Get boat usage

curl --request GET \
  --url https://boat.dev/api/v1/sandboxes/{sandboxId}/usage \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://boat.dev/api/v1/sandboxes/{sandboxId}/usage', 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://boat.dev/api/v1/sandboxes/{sandboxId}/usage",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://boat.dev/api/v1/sandboxes/{sandboxId}/usage"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://boat.dev/api/v1/sandboxes/{sandboxId}/usage")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "ok": true,
  "type": "sandbox.usage",
  "sandboxId": "bx_23456789",
  "sandboxType": "default",
  "billingMultiplier": 1,
  "since": "2026-09-01T00:00:00.000Z",
  "until": "2026-09-14T09:30:00.000Z",
  "seconds": 4980,
  "dollars": 0.0498,
  "secondsPerDollar": 100000,
  "running": false
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 400,
  "code": "invalid_json",
  "message": "Request body must be valid JSON.",
  "error": {
    "code": "invalid_json",
    "message": "Request body must be valid JSON.",
    "status": 400
  },
  "requestId": "req_01HX..."
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 401,
  "code": "unauthorized",
  "message": "Unauthorized",
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized",
    "status": 401
  },
  "requestId": "req_01HX..."
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 409,
  "code": "provider_not_configured",
  "message": "Prompting is locked until Codex is configured on the Agents page.",
  "requestId": "req_01HX...",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}