Account
Read the project's balance, reservations, monthly spending, limits, phone counts, price, countries, starter credit, top-up link and plan, and create a checkout link for credits.
The account belongs to the project that the key selects. Pricing and credits explains balances, reservations and the spending limit.
Get the account
GET /v1/account needs the phones:read scope.
It reads the project and touches no phone, so it is a cheap way to check that a key works.
curl https://phonebox.dev/v1/account \
-H "Authorization: Bearer $PHONEBOX_API_KEY"{
"project": "Checkout QA",
"balance_usd": "21.400000",
"reserved_usd": "7.200000",
"available_usd": "14.200000",
"spend_limit_usd": "100.000000",
"spent_this_month_usd": "4.120000",
"limits": { "phones": 10, "running": 5 },
"running": 1,
"phones": 3,
"price": { "per_minute_usd": "0.060000", "minimum_seconds": 60 },
"countries": [
{ "code": "AR", "name": "Argentina" },
{ "code": "AU", "name": "Australia" },
{ "code": "US", "name": "United States" }
],
"starter_credit": { "claimable": false, "amount_usd": "2.000000", "claim_url": null },
"top_up_url": "https://phonebox.dev/topup/MS5qZDdhYmMxMjMuMTc5NDc4NzIwMA.3q2-7wQx9Kx0pE3w1n1q0c2l6m8s9v4b7y5z0a1b2c3",
"plan": {
"tier": "starter",
"state": "subscribed",
"status": "active",
"trial_ends_at": null,
"renews_at": "2026-12-06T10:00:00.000Z",
"limits": {
"running_phones": 5, "phones": 10, "idle_max_seconds": 3600, "session_max_seconds": 10800, "team_members": 5,
"recordings": 20, "recording_days": 30, "saved_phone_days": null,
"features": { "countries": true, "device_writes": true, "recordings": true, "credit": true }
},
"next_url": "https://phonebox.dev/topup/MS5qZDdhYmMxMjMuMTc5NDc4NzIwMA.3q2-7wQx9Kx0pE3w1n1q0c2l6m8s9v4b7y5z0a1b2c3"
}
}| Field | Type | Meaning |
|---|---|---|
project | string | The project's name. |
balance_usd | money | Your credit, before reservations. |
reserved_usd | money | The credit held by open sessions. |
available_usd | money | What a new session can reserve: balance_usd minus reserved_usd, never below zero. |
spend_limit_usd | money | The monthly spending limit. |
spent_this_month_usd | money | What sessions that ended this calendar month, in UTC, were charged. |
limits.phones | integer | The most phones the project can have, not counting deleted or failed ones. |
limits.running | integer | The most phones the project can run at once. The limit counts all of your projects together. |
running | integer | Phones with an open session: creating, starting or ready. |
phones | integer | Phones that count toward the phone limit: every phone that isn't deleted or failed. |
price.per_minute_usd | money | The price of a phone-minute. |
price.minimum_seconds | integer | The shortest time a session is billed for. |
countries | array | The countries a phone can be created in, as {code, name}, sorted by name. Pass a code as country when you create a phone. The example shows three of them. A country is where the phone appears to be. |
starter_credit.claimable | boolean | Whether the project's owner can still unlock the one-time starter credit into this project by answering one question. Only an account's first project receives it. |
starter_credit.amount_usd | money | The starter credit's amount. |
starter_credit.claim_url | string or null | Where the owner signs in and answers the question, while claimable is true; otherwise null. Send your user here before you offer a paid top-up. |
top_up_url | string | A page where a member of this project signs in and pays for its credit, from $20. Give it to your user when credit runs out. It works for 30 days, and is the same link all day. |
Treat top_up_url like a key you'd share with your user only: anyone who has it can pay for this project's credit, though it shows nothing but the project's name and grants nothing else. Every insufficient_credits error on a project that can buy credit carries the same link in details.top_up_url.
The plan
plan says which plan the project is on and what to do next. The limits under it are what the plan allows; the top-level limits above are the project's own phone limits, which can be lower.
| Field | Type | Meaning |
|---|---|---|
plan.tier | string | legacy (a project from before plans), lapsed (no plan), trial (the free week), starter or pro. |
plan.state | string | What to do next: no_trial (the free week can start), trialing, subscribed, lapsed (start a plan again) or legacy. The same value is details.plan_state on an insufficient_credits error. |
plan.status | string or null | The subscription's status, such as trialing, active or past_due; null with no plan. |
plan.trial_ends_at | string or null | When the free week ends and the paid plan starts; null outside a free week. |
plan.renews_at | string or null | When the plan renews; null with no plan or one set to end. |
plan.limits.running_phones | integer | Phones that can run at once. |
plan.limits.phones | integer | Phones the project can hold. |
plan.limits.idle_max_seconds, plan.limits.session_max_seconds | integer | The longest idle timeout and session a phone can have. |
plan.limits.team_members | integer | People on the project, pending invites included. |
plan.limits.recordings, plan.limits.recording_days | integer | Recordings kept, and for how many days. 0 means none. |
plan.limits.saved_phone_days | integer or null | Days a parked phone is kept; null keeps it for good. |
plan.limits.features | object | countries, device_writes, recordings and credit, each true or false. A false one answers 403 plan_required. |
plan.next_url | string | A page where a member of the project signs in to take the next step for its state: start the free week, start Starter now, start a plan again, or add credit. |
The balance, reservations, spending, limits and price are always the project's. For a key limited to certain phones, running and phones count only the phones that key may use.
This endpoint returns no errors of its own. The common errors apply.
Create a checkout link
POST /v1/credits/checkout needs the phones:control scope.
Creates a checkout page where a person buys credits for the key's project. It is the same purchase as on the console's Billing page, so an agent or a terminal can ask for credit without sending anyone to the console. The body is optional.
| Field | Type | Default | Rules |
|---|---|---|---|
amount_usd | integer | 20 | The credit to buy, in whole US dollars, from 20 to 1000. |
{
"amount_usd": 25
}curl https://phonebox.dev/v1/credits/checkout \
-H "Authorization: Bearer $PHONEBOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"amount_usd": 25}'It answers 201 Created:
{
"url": "https://checkout.example.com/c/9f2b7c1e",
"amount_usd": 25
}| Field | Type | Meaning |
|---|---|---|
url | string | The checkout page, on our payment provider's site. Give it to a person, who pays there. Tax is added at checkout, and a discount code can be entered. |
amount_usd | integer | The credit the purchase adds, before tax and any discount. |
Nothing is charged until the person pays. The credit is added when the payment is confirmed, not when the page closes, so poll the account until balance_usd shows it. A link that nobody pays costs nothing.
| Error | When |
|---|---|
400 validation_failed | amount_usd isn't a whole number from 20 to 1000, or the body has another field. |
403 insufficient_scope | The key is Read-only. |
403 plan_required | The project is on the free week or has no plan, which can't buy credit (details.feature is credit). details.upgrade_url is where a person starts a plan. |
429 rate_limited | The project created 10 checkout links within the hour. Retry-After says when the next one can be created. |
503 billing_not_configured | Payments aren't connected on this deployment. |
The common errors apply too.