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 doesn’t expire while your account exists. 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.

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), and 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 and available_cents, and nothing is spent.

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 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. One purchase has a most; past it the answer is 400 invalid_gb, and its error names the range.

Required range: x >= 1
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