Get Boat limits

GET

limits

Get Boat limits

curl --request GET \
  --url https://boat.dev/api/v1/limits \
  --header 'Authorization: Bearer <token>'

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

fetch('https://boat.dev/api/v1/limits', 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/limits",
  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/limits"

	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/limits")

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": "limits.info",
  "canStart": true,
  "activeSandboxes": 1,
  "activeStates": [
    "provisioned",
    "cloning",
    "ready",
    "idle",
    "running"
  ],
  "sandboxPlanKey": "box_20",
  "sandboxPlanDollars": 20,
  "maxActiveSandboxes": 100,
  "maxCreationRequestsPerMinute": 10,
  "maxCreationRequestsPerDay": null,
  "startLimits": {
    "perMinute": 10,
    "perHour": 50,
    "perDay": 150
  },
  "starts": {
    "unlimited": false,
    "minute": {
      "limit": 10,
      "used": 3,
      "remaining": 7
    },
    "hour": {
      "limit": 50,
      "used": 12,
      "remaining": 38
    },
    "day": {
      "limit": 150,
      "used": 47,
      "remaining": 103
    }
  },
  "billingStatus": "active",
  "creditBalanceSeconds": 7200,
  "creditBalanceHours": 2,
  "packBalanceSeconds": 500000,
  "packBalanceHours": 138.89,
  "packBalanceDollars": 5
}

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

Authorizations

Authorization

string

header

required

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

Headers

X-Boat-Org

string

Same as the org query parameter. Query wins when both are set.

Query Parameters

org

string

Billing wallet for this request: an organization you belong to, by id (team_…) or by name as GET /orgs lists it (case-insensitive), or personal. Omitted, the account's active wallet applies (PATCH /orgs/active; personal until set). Two organizations sharing the name answer 409 ambiguous_org and need the id. Sandboxes, snapshots, and environments stay creator-private.

teamId

string

Legacy alias for org. Takes precedence over org / X-Boat-Org when set.

Response

Current creation and concurrent-boat limits.

boolean

required

Example:

true

type

string

required

Stable success envelope discriminator added by v1.

canStart

boolean

required

Whether the authenticated account can create or operate sandboxes right now.

activeSandboxes

integer

required

maxActiveSandboxes

integer

required

billingStatus

string

required

Account access state returned by the current backend. Billing endpoints are not part of v1.

accessTier

string

Example:

"trial"

blockedReason

string | null

currentLimits

object

Show child attributes

standardLimits

object

Show child attributes

trialLimits

object

Show child attributes

upgradeEffects

object

checkoutRequired

boolean

startBlockedReason

string | null

contactMessage

string | null

activeStates

string[]

maxCreationRequestsPerMinute

integer

maxCreationRequestsPerDay

integer | null

startLimits

object | null

Plan caps for machine starts. Null on unlimited accounts. Create, fork and resume each count as one start.

Show child attributes

starts

object

Remaining machine starts in the rolling minute, hour and day windows. Null windows mean the account is unlimited.

Show child attributes

creditBalanceHours

number | null

Remaining machine time in hours (creditBalanceSeconds / 3600). Null on unlimited accounts.

packBalanceHours

number

Remaining purchased credit packs in hours.

packBalanceDollars

number

Remaining purchased credit packs in dollars.

hasPaymentHistory

boolean

package

object

subscriptionQuotaSeconds

integer

subscriptionRemainingSeconds

integer

packBalanceSeconds

integer

creditPurchasedSeconds

integer

creditUsedSeconds

integer

liveUsageSeconds

integer

creditSecondsPerDollar

integer

sandboxPlanKey

string

Current plan key, or trial before any payment.

Example:

"box_20"

sandboxPlanDollars

number

Monthly price of the current plan in dollars.

sandboxPlanTiers

object[]

Every plan tier and its limits.

Show child attributes

accountPlan

string

Examples:

"user"

"service"

plan

string | null

service for service accounts, otherwise null.

planName

string | null

Service for service accounts, otherwise null.

serviceAccount

boolean

unlimited

boolean

True when the account has no machine-time or start limits.

hasSeatPlan

boolean

True when an organization has an active per-seat plan.

last24hUsageSeconds

integer

Machine time used in the last 24 hours, in seconds. Useful to estimate how long the balance lasts.

trialComputeCapSeconds

integer | null

Lifetime machine-time allowance for a trial that never paid. Null once the account has paid or has a plan.

trialLine

string | null

The trial limits in one readable line. Null on paid accounts.

giftLimit

object | null

Fair-use caps on a gifted account, or null when there are none.

Show child attributes

subscriptionStatus

string | null

subscriptionCancelAtPeriodEnd

boolean

hasSubscription

boolean

subscriptionTrialEndsAt

string<date-time> | null

subscriptionCurrentPeriodEnd

string<date-time> | null

creditBalanceSeconds

integer

teamId

string

Present when limits were read for a team wallet (?teamId=, ?org=, or X-Boat-Org).

teamRole

string

Caller's role on that team when teamId is present.

Get Boat limits

curl --request GET \
  --url https://boat.dev/api/v1/limits \
  --header 'Authorization: Bearer <token>'

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

fetch('https://boat.dev/api/v1/limits', 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/limits",
  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/limits"

	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/limits")

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": "limits.info",
  "canStart": true,
  "activeSandboxes": 1,
  "activeStates": [
    "provisioned",
    "cloning",
    "ready",
    "idle",
    "running"
  ],
  "sandboxPlanKey": "box_20",
  "sandboxPlanDollars": 20,
  "maxActiveSandboxes": 100,
  "maxCreationRequestsPerMinute": 10,
  "maxCreationRequestsPerDay": null,
  "startLimits": {
    "perMinute": 10,
    "perHour": 50,
    "perDay": 150
  },
  "starts": {
    "unlimited": false,
    "minute": {
      "limit": 10,
      "used": 3,
      "remaining": 7
    },
    "hour": {
      "limit": 50,
      "used": 12,
      "remaining": 38
    },
    "day": {
      "limit": 150,
      "used": 47,
      "remaining": 103
    }
  },
  "billingStatus": "active",
  "creditBalanceSeconds": 7200,
  "creditBalanceHours": 2,
  "packBalanceSeconds": 500000,
  "packBalanceHours": 138.89,
  "packBalanceDollars": 5
}

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