> ## 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.

# 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.

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](https://docs.orgo.ai/guides/browser-networking.md#residential-ip).

> [!WARNING]
>
> This spends credits. An agent should ask its person first.

Read the price with [Get residential data](https://docs.orgo.ai/api-reference/account/residential-data.md), 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](https://docs.orgo.ai/api-reference/account/residential-data.md). 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.

```bash theme={null}
curl -X POST https://www.orgo.ai/api/billing/residential-data/buy \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"gb": 5, "expected_price_cents": 300}'
```

## 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](#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](https://docs.orgo.ai/api-reference/account/residential-data.md) 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](https://docs.orgo.ai/api-reference/account/residential-data.md) 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.

```json theme={null}
{
  "error": "This account reached its limit of 20 GB a day. More can be added after 00:00 UTC. You were not charged.",
  "code": "RESIDENTIAL_DAILY_LIMIT",
  "retry_after": 3600,
  "buy_opens_at": "2026-11-11T00:00:00.000Z",
  "daily_gb_limit": 20,
  "retryable": true,
  "next": {
    "method": "GET",
    "url": "https://www.orgo.ai/api/billing/residential-data",
    "why": "Read daily_gb_left and buy_opens_at: more can be added from 00:00 UTC."
  },
  "docs_url": "https://www.orgo.ai/pricing.md#residential-ip-data"
}
```

## 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](https://docs.orgo.ai/api-reference/account/residential-data.md) 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:

| Answer | Meaning |
| - | - |
| `200` | Added and charged. `purchase.status` is `added`. |
| `202` `RESIDENTIAL_PURCHASE_PENDING` | The network hasn't confirmed it yet. The credits are held, not spent. Retry with the same key, or read it in [Get residential data](https://docs.orgo.ai/api-reference/account/residential-data.md). |
| `503` `RESIDENTIAL_DATA_UNAVAILABLE` | Not added and not charged. |
| `500` | The purchase couldn't be read. Retry with the same key, never a new one. |

`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.


## OpenAPI

````yaml POST /billing/residential-data/buy
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/buy:
    post:
      tags:
        - Account
      summary: Buy residential data
      description: >-
        Spends the account’s Orgo credits, the only call that does: turning a
        computer on never buys. Ask your human first. The workspace owner’s data
        is what that workspace’s computers use, and it counts down across all of
        them. Data isn’t refunded once added. Some sites can’t be reached this
        way.


        A session, or a key with full access or Billing write that covers the
        whole account. Buy any whole number of GB from 1 to the `max_gb` you
        read from `GET /api/billing/residential-data` (100 at most in one
        purchase, and at most what the account’s daily limit leaves today,
        `daily_gb_left`: 20 or less for most accounts), and send the price of 1
        GB you read there as `expected_price_cents`; if it has moved the answer
        is `409` `PRICE_CHANGED` and nothing is spent. A retry with the same
        `Idempotency-Key` answers what the first call came to, whatever has
        changed since: `200` added, `202` still open with the credits held,
        `503` not added and not charged.


        Up to `daily_gb_limit` GB of residential data can be added to an account
        a UTC day, 20 for most accounts, every way together: purchases from
        credits, card payments, auto-buy and its plan’s included data. Asking
        for more than is left today answers `409` `RESIDENTIAL_DATA_LIMITED`
        with `max_gb`; with nothing left today it is `429`
        `RESIDENTIAL_DAILY_LIMIT` with `buy_opens_at`. Neither spends, and
        neither counts as one of the day’s purchases.


        An account can make 10 purchases a UTC day, card payments started
        included. Past that the answer is `429` `rate_limited` with
        `buy_opens_at`.
      operationId: buyResidentialData
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          description: >-
            A new UUID for each purchase (8 to 255 printable characters). A
            retry with it never buys twice.
          schema:
            type: string
            minLength: 8
            maxLength: 255
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - gb
                - expected_price_cents
              properties:
                gb:
                  type: integer
                  minimum: 1
                  maximum: 100
                  description: >-
                    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`.
                expected_price_cents:
                  type: integer
                  description: >-
                    The price of 1 GB you agreed to, in cents, as `price_cents`
                    in `GET /api/billing/residential-data` read it.
                desktop_id:
                  type: string
                  format: uuid
                  description: >-
                    Optional. The computer this is for. Only its workspace owner
                    may buy for it: anyone else gets `403`
                    `ACCOUNT_OWNER_REQUIRED`.
            example:
              gb: 5
              expected_price_cents: 300
      responses:
        '200':
          description: Added and charged.
          content:
            application/json:
              schema:
                type: object
                required:
                  - purchase
                properties:
                  purchase:
                    $ref: '#/components/schemas/ResidentialDataPurchase'
              example:
                purchase:
                  id: 5f0c2b8e-3a1d-4c7e-9b2f-8d6a4e1c0b93
                  gb: 1
                  price_cents: 300
                  status: added
                  auto: false
                  created_at: '2026-11-10T14:07:12.000Z'
        '202':
          description: >-
            The network hasn’t confirmed it yet
            (`RESIDENTIAL_PURCHASE_PENDING`). The credits are held, not spent.
            Retry with the same key, or read it in `GET
            /api/billing/residential-data`.
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - message
                  - purchase
                properties:
                  code:
                    type: string
                    enum:
                      - RESIDENTIAL_PURCHASE_PENDING
                  message:
                    type: string
                  purchase:
                    $ref: '#/components/schemas/ResidentialDataPurchase'
                  retryable:
                    type: boolean
                  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
              example:
                code: RESIDENTIAL_PURCHASE_PENDING
                message: >-
                  The network hasn't confirmed it yet. Your credits are held,
                  not spent. It shows here once it does.
                purchase:
                  id: 5f0c2b8e-3a1d-4c7e-9b2f-8d6a4e1c0b93
                  gb: 1
                  price_cents: 300
                  status: pending
                  auto: false
                  created_at: '2026-11-10T14:07:12.000Z'
                retryable: true
                next:
                  method: GET
                  url: https://www.orgo.ai/api/billing/residential-data
                  why: Read whether the purchase has landed.
                docs_url: https://www.orgo.ai/pricing.md#residential-ip-data
        '400':
          description: >-
            No `Idempotency-Key` (`idempotency_key_required`), a bad one
            (`invalid_idempotency_key`), or `gb` out of range (`invalid_gb`).
            Nothing was spent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                no-key:
                  summary: No Idempotency-Key
                  value:
                    error: >-
                      Send an Idempotency-Key header, so a retry can never buy
                      twice.
                    code: idempotency_key_required
                bad-key:
                  summary: Bad Idempotency-Key
                  value:
                    error: >-
                      Idempotency-Key must be 8 to 255 printable characters,
                      such as a UUID.
                    code: invalid_idempotency_key
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: >-
            The credits don’t cover it (`INSUFFICIENT_CREDITS`), with
            `price_cents` (the price of 1 GB, as everywhere else), `total_cents`
            (`gb` times `price_cents`) and `available_cents`. Nothing was spent.
            It also carries `retryable`, `docs_url`, `next` (the call that adds
            credit) and `add_credit_url`. While nobody can add data to the
            account, the answer is the `503` instead. At the account’s limit for
            the day it is the `429` `RESIDENTIAL_DAILY_LIMIT`, and for more than
            today leaves the `409` `RESIDENTIAL_DATA_LIMITED`.
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                  - code
                properties:
                  error:
                    type: string
                  code:
                    type: string
                    enum:
                      - INSUFFICIENT_CREDITS
                  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
                  price_cents:
                    type: integer
                    description: The price of 1 GB, in cents.
                  total_cents:
                    type: integer
                    description: >-
                      What the purchase comes to: `gb` times `price_cents`, in
                      cents.
                  available_cents:
                    type: integer
                    description: The account’s credits, in cents.
                  add_credit_url:
                    type: string
                    format: uri
                    description: The page a person opens to add credit.
              example:
                error: >-
                  5 GB is $15.00 and your credits cover $1.20. Add credits, then
                  buy again.
                code: INSUFFICIENT_CREDITS
                price_cents: 300
                total_cents: 1500
                available_cents: 120
                retryable: false
                next:
                  method: POST
                  url: https://www.orgo.ai/api/credits/checkout
                  body:
                    amount_cents: 1000
                  why: Get a Checkout link for your human to pay, then retry.
                docs_url: https://www.orgo.ai/orgo.md
                add_credit_url: https://www.orgo.ai/settings/billing#credits
        '403':
          description: >-
            Nothing was spent. Not a paying account (`PLAN_REQUIRED`: it needs a
            paid plan or credit it bought; starting credit alone can’t buy
            residential data). No Linux computer outside Bops
            (`RESIDENTIAL_NO_COMPUTER`). While nobody can add data to the
            account, neither of these two: that is the `503`. Nor at the
            account’s limit for the day: that is the `429`
            `RESIDENTIAL_DAILY_LIMIT`. A key for a workspace or a computer
            (`ACCOUNT_KEY_REQUIRED`). An MCP sign-in, or a key without Billing
            write (`RESIDENTIAL_BUY_NEEDS_BILLING`, or `key_permission` from the
            key check). A computer of someone else’s workspace in `desktop_id`
            (`ACCOUNT_OWNER_REQUIRED`). An unclaimed agent account
            (`agent_account_unclaimed`). A share-link guest
            (`GUEST_RESTRICTED`). Each but `key_permission`,
            `agent_account_unclaimed` and `GUEST_RESTRICTED` also carries
            `retryable` and `docs_url`, and most carry `next`.
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                  - code
                properties:
                  error:
                    type: string
                  code:
                    type: string
                    enum:
                      - PLAN_REQUIRED
                      - RESIDENTIAL_NO_COMPUTER
                      - ACCOUNT_KEY_REQUIRED
                      - RESIDENTIAL_BUY_NEEDS_BILLING
                      - ACCOUNT_OWNER_REQUIRED
                      - agent_account_unclaimed
                      - 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:
                plan-required:
                  summary: Not a paying account
                  value:
                    error: >-
                      Residential IPs are for paying accounts. Pay by card in
                      Plan and billing, add credit, or pick a plan.
                    code: PLAN_REQUIRED
                    retryable: false
                    next:
                      method: GET
                      url: https://www.orgo.ai/pricing.md
                      why: See which plan includes this.
                    docs_url: https://www.orgo.ai/pricing.md
                no-computer:
                  summary: No Linux computer
                  value:
                    error: Residential data works on Linux computers. Add one first.
                    code: RESIDENTIAL_NO_COMPUTER
                    retryable: false
                    next:
                      method: POST
                      url: https://www.orgo.ai/api/computers
                      why: Add a Linux computer, then buy again.
                    docs_url: https://www.orgo.ai/pricing.md#residential-ip-data
                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
                needs-billing:
                  summary: MCP sign-in or a key without Billing write
                  value:
                    error: >-
                      Buying data spends your credits. Use a key with Billing
                      write access, or Orgo itself.
                    code: RESIDENTIAL_BUY_NEEDS_BILLING
                    retryable: false
                    next:
                      method: GET
                      url: https://www.orgo.ai/auth.md
                      why: >-
                        Ask your human for an API key with Billing write access,
                        then retry with it.
                    docs_url: https://www.orgo.ai/auth.md
                not-owner:
                  summary: Someone else’s computer
                  value:
                    error: Only the workspace owner can buy data for this computer.
                    code: ACCOUNT_OWNER_REQUIRED
                    retryable: false
                    docs_url: https://www.orgo.ai/pricing.md#residential-ip-data
                guest:
                  summary: A share-link guest
                  value:
                    error: Sign up to create your own workspace.
                    code: GUEST_RESTRICTED
        '409':
          description: >-
            Nothing was spent. The price moved (`PRICE_CHANGED`, with
            `price_cents`, the price of 1 GB now): read it, then buy again with
            it. Or less than `gb` can be added now (`RESIDENTIAL_DATA_LIMITED`,
            with `max_gb`): buy that much or less. Its words say when it is the
            account’s limit for the day that leaves less. Or a purchase for this
            account is still finishing (`RESIDENTIAL_PURCHASE_IN_PROGRESS`): try
            again in a minute.
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                  - code
                properties:
                  error:
                    type: string
                  code:
                    type: string
                    enum:
                      - PRICE_CHANGED
                      - RESIDENTIAL_DATA_LIMITED
                      - RESIDENTIAL_PURCHASE_IN_PROGRESS
                  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
                  price_cents:
                    type: integer
                    description: 'With `PRICE_CHANGED`: the price of 1 GB now, in cents.'
                  max_gb:
                    type: integer
                    description: >-
                      With `RESIDENTIAL_DATA_LIMITED`: the most one purchase can
                      add now.
              examples:
                price-changed:
                  summary: The price moved
                  value:
                    error: The price is now $3.00. Check it, then buy again.
                    code: PRICE_CHANGED
                    price_cents: 300
                    retryable: false
                    next:
                      method: GET
                      url: https://www.orgo.ai/api/billing/residential-data
                      why: Read the price, then buy again with it.
                    docs_url: https://www.orgo.ai/pricing.md#residential-ip-data
                limited:
                  summary: Less than gb can be added now
                  value:
                    error: >-
                      Up to 4 GB can be added right now. Buy that much or less.
                      You were not charged.
                    code: RESIDENTIAL_DATA_LIMITED
                    max_gb: 4
                limited-today:
                  summary: Less than gb is left of the account’s day
                  value:
                    error: >-
                      Up to 5 GB more can be added to this account today. Buy
                      that much or less. You were not charged.
                    code: RESIDENTIAL_DATA_LIMITED
                    max_gb: 5
                in-progress:
                  summary: A purchase is still finishing
                  value:
                    error: >-
                      A purchase for this account is still finishing. Try again
                      in a minute.
                    code: RESIDENTIAL_PURCHASE_IN_PROGRESS
                    retryable: true
                    next:
                      method: GET
                      url: https://www.orgo.ai/api/billing/residential-data
                      why: Read whether the purchase has landed.
                    docs_url: https://www.orgo.ai/pricing.md#residential-ip-data
        '429':
          description: >-
            Nothing was spent. The account made its 10 purchases of the UTC day
            (`rate_limited`, with `retry_after` and `buy_opens_at`, the next
            00:00 UTC). Each purchase from credits and each card payment started
            counts, paid or not, wherever it was started. Until then `GET
            /api/billing/residential-data` says `day_limit`. A `rate_limited`
            without `buy_opens_at` is the API’s own rate limit: wait
            `retry_after` seconds. Or the account was added its limit of GB for
            the UTC day, every way together (`RESIDENTIAL_DAILY_LIMIT`, with
            `retry_after`, `buy_opens_at`, `daily_gb_limit`, `retryable`, `next`
            and `docs_url`). Until then `GET /api/billing/residential-data` says
            `daily_data_limit`, and nothing lifts it sooner. It doesn’t count as
            one of the day’s purchases.
          headers:
            Retry-After:
              description: Seconds to wait.
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                  - code
                  - retry_after
                properties:
                  error:
                    type: string
                  code:
                    type: string
                    enum:
                      - rate_limited
                      - RESIDENTIAL_DAILY_LIMIT
                  retry_after:
                    type: integer
                    description: Seconds to wait.
                  buy_opens_at:
                    type: string
                    format: date-time
                    description: >-
                      With the day’s limit of purchases or of GB: when a
                      purchase can go again, the next 00:00 UTC.
                  daily_gb_limit:
                    type: integer
                    description: >-
                      With `RESIDENTIAL_DAILY_LIMIT`. 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.
                  retryable:
                    type: boolean
                    description: >-
                      With `RESIDENTIAL_DAILY_LIMIT`: whether the same request
                      may work later as it is.
                  next:
                    type: object
                    description: >-
                      With `RESIDENTIAL_DAILY_LIMIT`: the call that reads when
                      more can be added.
                    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:
                day-limit:
                  summary: The day’s purchases are used
                  value:
                    error: >-
                      This account reached its limit of 10 purchases today. Card
                      payments you started count too. You can buy again after
                      00:00 UTC. You were not charged.
                    code: rate_limited
                    retry_after: 3600
                    buy_opens_at: '2026-11-11T00:00:00.000Z'
                daily-data-limit:
                  summary: The day’s GB are used
                  value:
                    error: >-
                      This account reached its limit of 20 GB a day. More can be
                      added after 00:00 UTC. You were not charged.
                    code: RESIDENTIAL_DAILY_LIMIT
                    retry_after: 3600
                    buy_opens_at: '2026-11-11T00:00:00.000Z'
                    daily_gb_limit: 20
                    retryable: true
                    next:
                      method: GET
                      url: https://www.orgo.ai/api/billing/residential-data
                      why: >-
                        Read daily_gb_left and buy_opens_at: more can be added
                        from 00:00 UTC.
                    docs_url: https://www.orgo.ai/pricing.md#residential-ip-data
        '500':
          description: >-
            The purchase’s state couldn’t be read. It may have been charged:
            retry with the same `Idempotency-Key`, never a new one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: >-
                  Could not read this purchase. Try again with the same
                  Idempotency-Key.
        '503':
          description: >-
            Data can’t be added right now (`RESIDENTIAL_DATA_UNAVAILABLE`):
            paying, adding credit or a plan won’t help, so try later. Not added
            and not charged.
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                  - code
                properties:
                  error:
                    type: string
                  code:
                    type: string
                    enum:
                      - RESIDENTIAL_DATA_UNAVAILABLE
                  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
              example:
                error: >-
                  Residential data can't be added right now. You were not
                  charged.
                code: RESIDENTIAL_DATA_UNAVAILABLE
                retryable: true
                docs_url: https://www.orgo.ai/pricing.md#residential-ip-data
components:
  schemas:
    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
    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.
  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
  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.