Skip to main content
GET
Get residential data
Reads the calling account’s own residential data: what is left, what the plan includes this UTC month, the price of 1 GB, how much more can be added today, whether the account can buy now and why not, its credits, its purchases and its auto-buy setting. Read it before Buy residential data, and send its price_cents as expected_price_cents. See Residential IP.
It reads the account that calls, never a workspace’s: use the workspace owner’s sign-in or an account-wide key with Billing read. A key for one workspace or one computer answers 403 with code ACCOUNT_KEY_REQUIRED, and a share-link guest 403 with GUEST_RESTRICTED.
  • left_bytes counts data bought and this month’s included data. It is the network’s count at counted_at, less what the computers reported since, so it is an estimate between counts. While data can’t be added, or once the account reached its limit for the day, this month’s included data not added yet is left out of it and shows as included.waiting_bytes.
  • included is what the plan includes this UTC month: 1 GB on Starter, 5 GB on Growth, 20 GB on Scale and Enterprise. It is used before data bought, comes back in full at resets_at, and does not roll over. If the plan ends, pauses or switches before then, the amount follows that plan from that day. included.left_bytes can be a little more than gb_per_month, as data is added in whole GB.
  • included is absent on a plan with none, such as Free. A plan on a trial includes none until the trial ends, and included_after_trial says what it will include each month from then.
  • max_gb is the most one purchase can add now, in whole GB: at most 100, and at most daily_gb_left, so 20 or less for most accounts. It is less while the network has less to add, and 0 while nothing can be added. It follows the network’s newest count, so read it just before you buy. Send any gb from 1 to it to Buy residential data.
  • daily_gb_limit is the account’s limit of residential data added a UTC day: 20 GB for most accounts. 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. daily_gb_left is what the limit leaves today. Both are null where no limit applies. The limit is on adding data, not using it: data the account already has can still be used.
  • card_available is true when a person signed in to Orgo can pay by card in Settings → Plan & billing. It is always false with an API key, which can’t pay by card.
  • purchases lists the last 20, newest first. A pending purchase has its credits held, not spent; a returned one was not added, and its credits went back.
  • auto_buy.available is false while auto-buy isn’t offered, which is the case today. auto_buy is set by a person in Settings → Plan & billing, never by a key. It buys nothing until the account has bought once by hand (terms_accepted).

Why it can’t buy

can_buy is false with a buy_blocked_reason. The first reason that applies, in this order, is the one you read: needs_billing only takes the place of a buy the key alone stops. Any other reason stays as it is, since a key with Billing write would meet it too. buy_opens_at is present with day_limit and daily_data_limit only.

Authorizations

Authorization
string
header
required

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

Response

The account’s residential data.

left_bytes
integer
required

Data left: bought, and this month’s included data. As the network last counted it, less what the computers reported since, never below zero. An estimate between counts. While data can’t be added (buy_blocked_reason unavailable), or once the account reached its limit for the day (daily_data_limit), this month’s included data not added yet is left out: it is included.waiting_bytes instead.

counted_at
string<date-time> | null
required

When the network last counted the account’s use. Null before the first count.

price_cents
integer | null
required

The price of 1 GB, in cents. Null while it is not for sale.

can_buy
boolean
required

The account can buy data now.

buy_blocked_reason
enum<string> | null
required

Why can_buy is false, the first that applies in this order. Null when can_buy is true. unavailable: nobody can add data to this account right now: for example the network has none to add, residential data is blocked for the account, the account is being deleted, or a refund or dispute isn’t settled. Paying, adding credit or a computer won’t help, so try later. daily_data_limit: the account was added its limit of GB for the UTC day (daily_gb_limit), every way together: purchases from credits, card payments, auto-buy and the plan’s included data. More can be added at buy_opens_at, the next 00:00 UTC, and nothing lifts it sooner. The limit is on adding data, not using it. no_computer: no Linux computer outside Bops for the data to run on, on a free account too. Add one first. day_limit: the account made its 10 purchases of the UTC day. Each purchase from credits and each card payment started counts, paid or not. Buy again at buy_opens_at, the next 00:00 UTC. not_paying: no paid plan and no credit bought. Starting credit alone can’t buy residential data: pay by card signed in to Orgo, or add credit first. Once the account has paid, its whole balance pays, starting credit included. credit_short: the credits don’t cover 1 GB. needs_billing: this key has no Billing write, and nothing else stops the buy. Use a key with Billing write, or Orgo itself. Any other reason stays as it is, since a key with Billing write would meet it too.

Available options:
unavailable,
daily_data_limit,
no_computer,
day_limit,
not_paying,
credit_short,
needs_billing,
null
available_cents
integer | null
required

The account’s credits, in cents, when they were read.

purchases
object[]
required

Newest first, at most 20. Included data is not a purchase.

auto_buy
object
required

Buying 1 GB from credits when data falls under 0.25 GB. Set by a person in Plan and billing, and only there. It buys nothing until the account has bought once by hand, which accepts the Residential IPs terms (terms_accepted).

buy_opens_at
string<date-time>

With day_limit or daily_data_limit only: when a purchase can go again, the next 00:00 UTC.

terms_accepted
boolean

The account has bought before, and with that accepted the Residential IPs terms. Auto-buy buys nothing while this is false. Absent while it is not for sale.

card_available
boolean

A person signed in to Orgo can pay for data by card in Plan and billing, also with no paid plan and no credit bought (not_paying). False with an API key, which can’t pay by card. can_buy and buy_blocked_reason still say whether a purchase can go now. Absent while it is not for sale.

max_gb
integer

The most one purchase can add now, in whole GB: at most 100, and at most daily_gb_left where the account has a daily limit, so 20 or less for most accounts. Less while the network has less to add, and 0 while nothing can be added. It follows the network’s newest count, so read it just before you buy. Absent while it is not for sale.

Required range: x >= 0
daily_gb_limit
integer | null

The account’s limit of residential data added a UTC day, in whole GB: 20 for most accounts. Every way data is added counts together: purchases from credits, card payments, auto-buy and the plan’s included data. Null where no limit applies. Absent while it is not for sale.

daily_gb_left
integer | null

What daily_gb_limit leaves this UTC day, in whole GB. At 0, buy_blocked_reason is daily_data_limit until buy_opens_at, the next 00:00 UTC. Null where no limit applies, or when it couldn’t be read. Absent while it is not for sale.

included
object

Residential data the plan includes this UTC month, used before data bought. Absent on a plan with none, such as Free, and on a plan on a trial, which includes none until the trial ends (included_after_trial).

included_after_trial
object

A plan on a trial includes no residential data until the trial ends: what it will include each UTC month from then. Absent otherwise, and never with included.