Account
Buy residential data
Buy whole GB of residential IP data from your Orgo credits, at $3 per GB, up to what your account can still add today. Retries with the same Idempotency-Key never buy twice.
POST
Buy residential data
Buys residential data from the account’s Orgo credits, at $3 per GB. It is the only call that spends on residential data: turning a computer’s residential IP on never buys. Data is added at once, isn’t refunded once added, and is lost if the account is deleted. See Residential IP.
Read the price with Get residential data, then send it as
expected_price_cents. If the price has moved, the answer is 409 with code PRICE_CHANGED and the new price_cents, and nothing is spent.
Buy as many whole GB as you need in one call: gb is any whole number from 1 to max_gb in Get residential data. That is at most 100, and at most what the account can still add today (daily_gb_left), so 20 or less for most accounts. It is less while the network has less to add. max_gb follows the network’s newest count, so read it just before you buy. The charge is gb times price_cents. Ask for more than can be added now and the answer is 409 RESIDENTIAL_DATA_LIMITED with max_gb, and nothing is spent: buy that much or less.
Who can buy
The data belongs to the workspace owner, and every computer in the owner’s workspaces draws on it. Buy with the owner’s sign-in, or a key for the whole account with full access or Billing write.- The account needs a paid plan or credit it bought (
403PLAN_REQUIRED). Starting credit alone can’t buy residential data. Once the account has paid by card or added credit, its whole balance pays, starting credit included. - The account needs a Linux computer outside Bops (
403RESIDENTIAL_NO_COMPUTER). - A key for one workspace or one computer answers
403ACCOUNT_KEY_REQUIRED. An MCP sign-in answers403RESIDENTIAL_BUY_NEEDS_BILLING. A share-link guest answers403GUEST_RESTRICTED. desktop_idis optional. When sent, only that computer’s workspace owner may buy: anyone else gets403ACCOUNT_OWNER_REQUIRED.- When the credits don’t cover it, the answer is
402INSUFFICIENT_CREDITSwithprice_cents(the price of 1 GB),total_cents(gbtimesprice_cents) andavailable_cents, and nothing is spent. - While nobody can add data to the account, the answer is
503RESIDENTIAL_DATA_UNAVAILABLEin place ofPLAN_REQUIRED,RESIDENTIAL_NO_COMPUTERorINSUFFICIENT_CREDITS. Paying, adding credit or a computer won’t help, so try again later. Nothing is spent. - At the account’s limit for the day, the answer is
429RESIDENTIAL_DAILY_LIMITin place of those three, as described in GB a day. With credits short andgbover what is left today, it is409RESIDENTIAL_DATA_LIMITEDin place ofINSUFFICIENT_CREDITS.
GB a day
Up to 20 GB of residential data can be added to an account a UTC day.daily_gb_limit in Get residential data says the account’s limit, and daily_gb_left what is left of it today. Every way data is added counts together: purchases from credits, card payments, auto-buy and the plan’s included data, which is added a GB at a time as it is used. The limit is on adding data, not using it: data the account already has can still be used.
- Ask for more than is left today and the answer is
409RESIDENTIAL_DATA_LIMITEDwithmax_gb, in words that say it is the account’s limit for today. Buy that much or less. - With nothing left today the answer is
429RESIDENTIAL_DAILY_LIMITwithretry_after,buy_opens_at(the next 00:00 UTC) anddaily_gb_limit. Until then Get residential data saysbuy_blocked_reasondaily_data_limitwith the samebuy_opens_at. Nothing lifts it sooner.
Purchases a day
An account can make 10 purchases a UTC day. Each purchase from credits counts, and so does each card payment started in Orgo, paid or not. Past the limit the answer is429 rate_limited with retry_after and buy_opens_at, the next 00:00 UTC, and nothing is spent. Until then Get residential data says buy_blocked_reason day_limit with the same buy_opens_at. A 429 without buy_opens_at is the API’s own rate limit: wait retry_after seconds.
Retries never buy twice
Send a new UUID asIdempotency-Key for each purchase. A retry with the same key answers what the first call came to, whatever has changed since:
409 RESIDENTIAL_PURCHASE_IN_PROGRESS means another purchase for the account is still finishing. Try again in a minute.
Auto-buy
Auto-buy isn’t available yet:auto_buy.available is false on every account, and nothing turns it on. When it is available, it buys 1 GB when the account’s data falls under 0.25 GB, up to a monthly limit, after the month’s included data is used. It starts after the account’s first purchase by hand, which accepts the Residential IPs terms: until then terms_accepted is false and auto-buy buys nothing. Only a person signed in to Orgo turns it on, in Settings → Plan & billing. No key can.Authorizations
Headers
Body
application/json
Whole GB to buy in one purchase, from 1 to max_gb in GET /api/billing/residential-data. Charged gb times the price of 1 GB. Past 100 the answer is 400 invalid_gb; past what can be added now, or what the account’s daily limit leaves today, it is 409 RESIDENTIAL_DATA_LIMITED with max_gb; with nothing left today it is 429 RESIDENTIAL_DAILY_LIMIT.
Required range:
1 <= x <= 100