> ## 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, the most one purchase can add, how much more can be added today, why it can't buy now, 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, 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](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. 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](https://docs.orgo.ai/api-reference/account/buy-residential-data.md).
* `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:

| `buy_blocked_reason` | Why | What to do |
| - | - | - |
| `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. | Try again later. Paying, adding credit or a computer won't help. |
| `daily_data_limit` | The account was added its limit of GB for the UTC day (`daily_gb_limit`), every way together: purchases, card payments and the plan's included data. | More can be added at `buy_opens_at`, the next 00:00 UTC. Nothing lifts it sooner. |
| `no_computer` | The account has no Linux computer outside Bops for the data to run on. Free accounts too. | Add a Linux computer. |
| `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. Once the account has paid, its whole balance pays, starting credit included. |
| `credit_short` | The credits don't cover 1 GB. | Add credit, or pay by card signed in to Orgo. |
| `needs_billing` | The key has no Billing write, and nothing else stops the buy. | Use a key with Billing write, or Orgo itself. |

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


## 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`, and `buy_opens_at` once the day’s purchases or the
        day’s GB are used; `available_cents`; `max_gb`, the most one purchase
        can add now; `daily_gb_limit` and `daily_gb_left`, the account’s limit
        of GB a UTC day and what it leaves today; `purchases`; `auto_buy`; and
        `included`, what the plan includes this UTC month, or
        `included_after_trial` while a trial includes none. 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`. A key without Billing write reads `can_buy:
        false` with `needs_billing` where nothing else stops the buy. A key
        reads `card_available: false`: only a person signed in to Orgo pays by
        card.
      operationId: getResidentialData
      responses:
        '200':
          description: The account’s residential data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResidentialData'
              examples:
                can-buy:
                  summary: Can buy
                  value:
                    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
                    card_available: false
                    max_gb: 20
                    daily_gb_limit: 20
                    daily_gb_left: 20
                    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: false
                      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'
                day-limit:
                  summary: The day’s purchases are used
                  value:
                    left_bytes: 0
                    counted_at: '2026-11-10T23:05:00.000Z'
                    price_cents: 300
                    can_buy: false
                    buy_blocked_reason: day_limit
                    buy_opens_at: '2026-11-11T00:00:00.000Z'
                    available_cents: null
                    terms_accepted: true
                    card_available: false
                    max_gb: 10
                    daily_gb_limit: 20
                    daily_gb_left: 10
                    purchases:
                      - id: 5f0c2b8e-3a1d-4c7e-9b2f-8d6a4e1c0b93
                        gb: 1
                        price_cents: 300
                        status: added
                        auto: false
                        created_at: '2026-11-10T22:41:09.000Z'
                    auto_buy:
                      enabled: false
                      available: false
                      monthly_cap_gb: null
                      price_cents: null
                      paused_reason: null
                      bought_this_month_gb: 0
                daily-data-limit:
                  summary: The day’s GB are used
                  value:
                    left_bytes: 6442450944
                    counted_at: '2026-11-10T21:05:00.000Z'
                    price_cents: 300
                    can_buy: false
                    buy_blocked_reason: daily_data_limit
                    buy_opens_at: '2026-11-11T00:00:00.000Z'
                    available_cents: null
                    terms_accepted: true
                    card_available: false
                    max_gb: 0
                    daily_gb_limit: 20
                    daily_gb_left: 0
                    purchases:
                      - id: 9a7d3c41-6e2b-4f08-b1d5-2c8e7f0a4b16
                        gb: 20
                        price_cents: 6000
                        status: added
                        auto: false
                        created_at: '2026-11-10T15:20:31.000Z'
                    auto_buy:
                      enabled: false
                      available: false
                      monthly_cap_gb: null
                      price_cents: null
                      paused_reason: null
                      bought_this_month_gb: 0
                waiting:
                  summary: Included data waiting to be added
                  value:
                    left_bytes: 811597824
                    counted_at: '2026-11-10T14:05:00.000Z'
                    price_cents: 300
                    can_buy: false
                    buy_blocked_reason: unavailable
                    available_cents: null
                    terms_accepted: false
                    card_available: false
                    max_gb: 0
                    daily_gb_limit: 20
                    daily_gb_left: 20
                    purchases: []
                    auto_buy:
                      enabled: false
                      available: false
                      monthly_cap_gb: null
                      price_cents: null
                      paused_reason: null
                      bought_this_month_gb: 0
                    included:
                      plan: Growth
                      gb_per_month: 5
                      used_bytes: 262144000
                      left_bytes: 811597824
                      waiting_bytes: 4294967296
                      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. 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:
          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:
            - unavailable
            - daily_data_limit
            - no_computer
            - day_limit
            - not_paying
            - credit_short
            - needs_billing
            - null
          description: >-
            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.
        buy_opens_at:
          type: string
          format: date-time
          description: >-
            With `day_limit` or `daily_data_limit` only: when a purchase can go
            again, the next 00:00 UTC.
        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.
        card_available:
          type: boolean
          description: >-
            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:
          type: integer
          minimum: 0
          description: >-
            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.
        daily_gb_limit:
          type:
            - integer
            - 'null'
          description: >-
            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:
          type:
            - integer
            - 'null'
          description: >-
            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.
        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, and on a plan on a
            trial, which includes none until the trial ends
            (`included_after_trial`).
          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, never past `gb_per_month`. An
                estimate between counts.
            left_bytes:
              type: integer
              description: >-
                The plan’s data left this month. It can be a little more than
                `gb_per_month`, as data is added in whole GB, or more after a
                switch to a smaller plan: all of it is still the plan’s. Not
                `waiting_bytes`.
            waiting_bytes:
              type: integer
              description: >-
                This month’s included data not added to the account yet that
                can’t be added now: while data can’t be added
                (`buy_blocked_reason` `unavailable`), or once the account
                reached its limit for the day (`daily_data_limit`). It is in
                neither `left_bytes`, and not used either. Absent while there is
                none.
            resets_at:
              type: string
              format: date-time
              description: >-
                When it comes back: the start of the next UTC month, on the plan
                the account has then. What is left does not roll over. If the
                plan ends, pauses or switches first, the amount follows that
                plan from that day.
        included_after_trial:
          type: object
          required:
            - plan
            - gb_per_month
          description: >-
            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`.
          properties:
            plan:
              type: string
              enum:
                - Starter
                - Growth
                - Scale
                - Enterprise
            gb_per_month:
              type: integer
    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.