Provision Box

Provision a new box for the authenticated project.

Idempotent-ish: if a live box already exists, returns 409. After bux down, the row is reused (preserving profile_id + size — the user’s previous choice carries over unless they explicitly pass a new size).

Requires a paying / comped project. Free-tier projects are rejected with 402. Min-balance scales by size ($5 /$10 / $20 for small / medium / large) so users with ~5 days of runway can deploy. See common/models/bux/sizing.py.

POST /boxes

Provision Box

JavaScript

const options = {
  method: 'POST',
  headers: {'X-Browser-Use-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({profile_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a'})
};

fetch('https://api.browser-use.com/api/v3/boxes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url https://api.browser-use.com/api/v3/boxes \
  --header 'Content-Type: application/json' \
  --header 'X-Browser-Use-API-Key: <api-key>' \
  --data '
{
  "profile_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'

import requests

url = "https://api.browser-use.com/api/v3/boxes"

payload = { "profile_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a" }
headers = {
    "X-Browser-Use-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

200

{
  "box": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "profile_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "size_spec": {
      "vcpu": 123,
      "ram_gb": 123,
      "disk_gb": 123,
      "daily_usd": 123,
      "min_balance_usd": 123
    },
    "ec2_instance_id": "<string>",
    "public_ip": "<string>",
    "status_detail": "<string>",
    "claude_authed": true,
    "tg_installed": true,
    "tg_bot_username": "<string>",
    "dsp_enabled": true,
    "live_browser_url": "<string>",
    "last_heartbeat_at": "2023-11-07T05:31:56Z",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "trial_ends_at": "2023-11-07T05:31:56Z"
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Authorizations

X-Browser-Use-API-Key · string · header · required

Body

application/json

profile_id · string<uuid> | null

size · enum<string> | null

Available options: small, medium, large

Response

200

application/json

Successful Response

box · BoxView · object · required

Show child attributes