Pools API reference
Manage reserved browser pools over the API: create with a total size, read warm and in-use counters, resize with PATCH and delete cleanly.
Last updated:
A pool keeps browsers running ahead of demand, so a session claims one instead of waiting for a container build. Five endpoints manage them, all behind the familiar bearer authentication with your bb_ key. Reserved browsers are a paid entitlement, billed as a holding while they are reserved.
/v1/pools
Creates a pool and starts filling it to size.
Create body
| Name | Type | Description |
|---|---|---|
name
required
|
string | Up to 80 characters. |
size
required
|
integer | 1 to 250 — and a total: warm browsers plus browsers currently claimed by sessions. |
shape
|
object | The browser shape every pooled browser is launched with; it is fixed for the pool's life. |
/v1/pools
Lists your pools with their counters.
/v1/pools/:id
Reads one pool, including `warm` and `inUse`.
Counters, and two refusals
warm and inUse are live numbers from the fleet — or null when the fleet could not be asked, which is reported rather than guessed at. Two refusals define pooled sessions: an empty pool never falls back to a cold start (the pool would become a hint instead of a capacity plan), and a session may not request a shape different from the pool's, because those browsers are already running with their locale fixed at launch.
/v1/pools/:id
Renames or resizes the pool; the body takes `name`, `size` or both.
/v1/pools/:id
Deletes the pool; sessions that already claimed a browser keep it.
Round trip over a pool
Creates a one-browser pool, reads the counters and deletes it again.
Requires: api-key paid-plan
BASE="https://browserberg.com"
AUTH="Authorization: Bearer $BROWSERBERG_API_KEY"
JSON="Content-Type: application/json"
# Size is a TOTAL: warm browsers plus browsers already claimed by sessions.
POOL=$(curl -s -X POST "$BASE/v1/pools" -H "$AUTH" -H "$JSON" \
-d '{ "name": "Docs walkthrough", "size": 1, "shape": { "locale": "de-DE" } }')
PID=$(echo "$POOL" | python3 -c 'import json,sys; print(json.load(sys.stdin)["pool"]["id"])')
curl -s "$BASE/v1/pools/$PID" -H "$AUTH" \
| python3 -c 'import json,sys; p = json.load(sys.stdin)["pool"]; print(json.dumps({
"name": p["name"], "size": p["size"], "warm": p["warm"], "inUse": p["inUse"]}, indent=2))'
curl -s -X DELETE "$BASE/v1/pools/$PID" -H "$AUTH" > /dev/null