Skip to main content
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.
This spends credits. An agent should ask its person first.
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 (403 PLAN_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 (403 RESIDENTIAL_NO_COMPUTER).
  • A key for one workspace or one computer answers 403 ACCOUNT_KEY_REQUIRED. An MCP sign-in answers 403 RESIDENTIAL_BUY_NEEDS_BILLING. A share-link guest answers 403 GUEST_RESTRICTED.
  • desktop_id is optional. When sent, only that computer’s workspace owner may buy: anyone else gets 403 ACCOUNT_OWNER_REQUIRED.
  • When the credits don’t cover it, the answer is 402 INSUFFICIENT_CREDITS with price_cents (the price of 1 GB), total_cents (gb times price_cents) and available_cents, and nothing is spent.
  • While nobody can add data to the account, the answer is 503 RESIDENTIAL_DATA_UNAVAILABLE in place of PLAN_REQUIRED, RESIDENTIAL_NO_COMPUTER or INSUFFICIENT_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 429 RESIDENTIAL_DAILY_LIMIT in place of those three, as described in GB a day. With credits short and gb over what is left today, it is 409 RESIDENTIAL_DATA_LIMITED in place of INSUFFICIENT_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 409 RESIDENTIAL_DATA_LIMITED with max_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 429 RESIDENTIAL_DAILY_LIMIT with retry_after, buy_opens_at (the next 00:00 UTC) and daily_gb_limit. Until then Get residential data says buy_blocked_reason daily_data_limit with the same buy_opens_at. Nothing lifts it sooner.
Neither spends, and neither counts as one of the day’s 10 purchases.

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 is 429 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 as Idempotency-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

Authorization
string
header
required

API key authentication. Get your key at orgo.ai/workspaces

Headers

Idempotency-Key
string
required

A new UUID for each purchase (8 to 255 printable characters). A retry with it never buys twice.

Required string length: 8 - 255

Body

application/json
gb
integer
required

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
expected_price_cents
integer
required

The price of 1 GB you agreed to, in cents, as price_cents in GET /api/billing/residential-data read it.

desktop_id
string<uuid>

Optional. The computer this is for. Only its workspace owner may buy for it: anyone else gets 403 ACCOUNT_OWNER_REQUIRED.

Response

Added and charged.

purchase
object
required