> ## Documentation Index > Fetch the complete documentation index at: https://docs.orgo.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get residential data > How much residential IP data your account has left, what your plan includes this month, the price of 1 GB, and what you bought. Reads the calling account's own residential data: what is left, what the plan includes this UTC month, the price of 1 GB, whether the account can buy now, its credits, its purchases and its auto-buy setting. Read it before [Buy residential data](https://docs.orgo.ai/api-reference/account/buy-residential-data.md), and send its `price_cents` as `expected_price_cents`. See [Residential IP](https://docs.orgo.ai/guides/browser-networking.md#residential-ip). > [!NOTE] > > 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`. ```bash theme={null} curl https://www.orgo.ai/api/billing/residential-data \ -H "Authorization: Bearer $ORGO_API_KEY" ``` * `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. * `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. It is absent on a plan with none, such as Free. * `can_buy` is false with `buy_blocked_reason`: `not_paying` (the account needs a paid plan or credit it bought), `credit_short` (the credits don't cover 1 GB) or `unavailable` (data can't be added right now). * `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` 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`). ## OpenAPI ````yaml GET /billing/residential-data openapi: 3.1.0 info: title: Orgo API description: >- Launch cloud computers that AI agents can control and interact with. Create workspaces, provision computers, and control them programmatically. version: 2.0.0 contact: name: Orgo Support email: contact@orgo.ai url: https://orgo.ai servers: - url: https://www.orgo.ai/api description: Production security: - bearerAuth: [] tags: - name: Support description: >- Orgo’s support agent, for programs: ask how to do something in Orgo and get an answer with full URLs and copyable commands. - name: Account description: >- Account capacity: how many computers an account may run, and adding or giving back more. Residential data: what the account has left for residential IPs, and buying more from credits. - name: Agent accounts description: >- Accounts an AI agent makes for itself, and the claim link a person uses to take one over. - name: Clients description: >- Run Orgo for your clients from your own app: a workspace and scoped key each, billed to you or to them. - name: Workspaces description: Organize computers into named workspaces - name: Computers description: Provision and manage virtual computers - name: Public URLs description: Share an app running on a computer at an https address on orgo.dev. - name: Computer Lifecycle description: Start, stop, and restart computers - name: Computer Actions description: Control mouse, keyboard, and execute commands - name: Screens description: >- More than one desktop on a single computer. Each screen is its own X server with its own cursor and window manager, so an agent working on one cannot disturb another. - name: Files description: Upload and download files - name: Templates description: Author, build, and launch reproducible computers from templates - name: Chat description: Run an agent on a computer through OpenAI-compatible chat completions. - name: Workflows description: >- Routines that run the same way every time: a start, then steps. Make them from plain words or lines, check them, run them and follow their runs (in preview). paths: /billing/residential-data: get: tags: - Account summary: Get residential data description: >- The calling account’s own residential data: `left_bytes` from the network’s count at `counted_at`, less what its computers reported since; `price_cents` for 1 GB (null while it is not for sale); `can_buy` with `buy_blocked_reason`; `available_cents`; `purchases`; `auto_buy`; and `included`, what the plan includes this UTC month. It reads the account that calls, never a workspace’s. Billing read, on a session or a key for the whole account: a key for a workspace or a computer answers `403` `ACCOUNT_KEY_REQUIRED`. operationId: getResidentialData responses: '200': description: The account’s residential data. content: application/json: schema: $ref: '#/components/schemas/ResidentialData' example: left_bytes: 1885339648 counted_at: '2026-11-10T14:05:00.000Z' price_cents: 300 can_buy: true buy_blocked_reason: null available_cents: 1250 terms_accepted: true purchases: - id: 5f0c2b8e-3a1d-4c7e-9b2f-8d6a4e1c0b93 gb: 1 price_cents: 300 status: added auto: false created_at: '2026-11-03T09:12:44.000Z' auto_buy: enabled: false available: true monthly_cap_gb: null price_cents: null paused_reason: null bought_this_month_gb: 0 included: plan: Starter gb_per_month: 1 used_bytes: 262144000 left_bytes: 811597824 resets_at: '2026-12-01T00:00:00.000Z' '401': $ref: '#/components/responses/Unauthorized' '403': description: >- A key for one workspace or one computer, a computer’s own key, or an MCP sign-in (`ACCOUNT_KEY_REQUIRED`, with `retryable`, `next` and `docs_url`). A restricted key without Billing read answers `key_permission`. A share-link guest answers `GUEST_RESTRICTED`. content: application/json: schema: type: object required: - error - code properties: error: type: string code: type: string enum: - ACCOUNT_KEY_REQUIRED - key_permission - GUEST_RESTRICTED retryable: type: boolean description: Whether the same request may work later as it is. next: type: object description: The call that fixes it. required: - method - url - why properties: method: type: string enum: - GET - POST url: type: string format: uri body: type: object description: What to send, when the call needs a body. why: type: string description: >- What the call does, for an agent deciding whether to make it. docs_url: type: string format: uri examples: account-key: summary: A key for a workspace or a computer value: error: Buy data with your own sign-in or account key. code: ACCOUNT_KEY_REQUIRED retryable: false next: method: GET url: https://www.orgo.ai/auth.md why: Use your own sign-in or an account key, then retry. docs_url: https://www.orgo.ai/auth.md guest: summary: A share-link guest value: error: Sign up to create your own workspace. code: GUEST_RESTRICTED '429': $ref: '#/components/responses/RateLimited' '503': description: The data couldn’t be read. Try again. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Residential data is temporarily unavailable. components: schemas: ResidentialData: type: object required: - left_bytes - counted_at - price_cents - can_buy - buy_blocked_reason - available_cents - purchases - auto_buy properties: left_bytes: type: integer description: >- 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. counted_at: type: - string - 'null' format: date-time description: >- When the network last counted the account’s use. Null before the first count. price_cents: type: - integer - 'null' description: The price of 1 GB, in cents. Null while it is not for sale. can_buy: type: boolean description: The account can buy data now. buy_blocked_reason: type: - string - 'null' enum: - not_paying - credit_short - unavailable - null description: >- `not_paying`: the account needs a paid plan or credit it bought. `credit_short`: the credits don’t cover 1 GB. `unavailable`: data can’t be added right now. Null when `can_buy` is true. available_cents: type: - integer - 'null' description: The account’s credits, in cents, when they were read. terms_accepted: type: boolean description: >- 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. purchases: type: array items: $ref: '#/components/schemas/ResidentialDataPurchase' description: Newest first, at most 20. Included data is not a purchase. auto_buy: type: object required: - enabled description: >- 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`). properties: enabled: type: boolean available: type: boolean description: >- It can be turned on now. Absent while residential data is not for sale. monthly_cap_gb: type: - integer - 'null' description: The most it buys in a UTC month, 1 to 100. price_cents: type: - integer - 'null' description: >- The price of 1 GB the person agreed to. A new price pauses auto-buy until they save it again. paused_reason: type: - string - 'null' enum: - no_credit - unavailable - cap_reached - not_eligible - price_changed - null description: Why it is paused. Null when it is not. bought_this_month_gb: type: number description: GB it bought this UTC month. included: type: object required: - plan - gb_per_month - used_bytes - left_bytes - resets_at description: >- Residential data the plan includes this UTC month, used before data bought. Absent on a plan with none, such as Free. properties: plan: type: string enum: - Starter - Growth - Scale - Enterprise gb_per_month: type: integer description: 1 on Starter, 5 on Growth, 20 on Scale and Enterprise. used_bytes: type: integer description: >- Used this UTC month, as the network last counted it plus what the computers reported since. An estimate between counts. left_bytes: type: integer resets_at: type: string format: date-time description: >- When it comes back: the start of the next UTC month. What is left does not roll over. Error: type: object description: >- The base error body. Every failure carries `error`; individual endpoints add the fields named in the schemas below. required: - error properties: error: type: string description: Human-readable message. example: Access denied code: type: string description: >- Machine-readable reason. Present on the failures that define one, absent otherwise. ResidentialDataPurchase: type: object required: - id - gb - price_cents - status - created_at properties: id: type: string format: uuid gb: type: integer price_cents: type: integer description: What it cost, in cents. status: type: string enum: - pending - added - returned description: >- `pending`: the credits are held, not spent. `added`: charged. `returned`: not added, and the credits went back. auto: type: boolean description: Bought by auto-buy, not by hand. created_at: type: string format: date-time RateLimited: type: object required: - error - code - limit - retry_after properties: error: type: string description: Which limit, in plain words, and when to try again. code: type: string const: rate_limited limit: type: string enum: - computer_create_per_minute - computer_create_per_hour - computer_create_per_day - computer_lifecycle_per_minute - computer_lifecycle_per_computer_per_minute - computer_control_per_minute - computer_control_per_computer_per_minute - chat_runs_per_minute - chat_runs_concurrent - workspace_create_per_hour - api_other_per_minute retry_after: type: integer minimum: 1 description: Seconds to wait. example: error: >- Too many API requests this minute (120 a minute on your plan). Try again in 12 seconds. code: rate_limited limit: api_other_per_minute retry_after: 12 responses: Unauthorized: description: 'No usable credential. Send `Authorization: Bearer $ORGO_API_KEY`.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - type: object properties: docs: type: string format: uri description: 'How to sign in: `https://www.orgo.ai/auth.md`.' examples: invalid-key: summary: The key is not one of yours value: error: Invalid API key docs: https://www.orgo.ai/auth.md no-credential: summary: No key and no session value: error: Authentication required docs: https://www.orgo.ai/auth.md headers: WWW-Authenticate: description: '`Bearer realm="Orgo API"`.' schema: type: string RateLimited: description: >- Over one of the account's plan rate limits (`rate_limited`): `limit` names it, and `retry_after` and `Retry-After` say how many seconds to wait. Limits are per account, the workspace owner's when the request acts on a computer or a workspace, and set by its plan. See [Account limits and rate limits](/guides/account-limits#plan-rate-limits). headers: Retry-After: $ref: '#/components/headers/RetryAfter' RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/RateLimited' headers: RetryAfter: description: Seconds to wait before asking again. schema: type: integer minimum: 1 RateLimitLimit: description: The tightest limit this request counts against. schema: type: integer RateLimitRemaining: description: How many are left of it in this window. schema: type: integer RateLimitReset: description: Seconds until its window starts again. schema: type: integer securitySchemes: bearerAuth: type: http scheme: bearer description: API key authentication. Get your key at orgo.ai/workspaces ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.