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

> Whether the computer's Chrome uses a residential IP, its exit IP, and the account's residential data.

Returns the computer's browser route and the account's residential data. See [Residential IP](https://docs.orgo.ai/guides/browser-networking.md#residential-ip).

`exit_ip` is the last IP seen. Add `?check=1` to read it through the proxy now. The answer then adds `changed` and `checked_at`. A check uses a few KB of data, and a computer allows 6 a minute.

`proxy_on` is also true when the computer uses [your own proxy](https://docs.orgo.ai/guides/browser-networking.md#bring-your-own-proxy), so read `mode` to tell them apart.

## Data fields

`quota` is the workspace owner's data, shared by every computer of theirs. On a Linux computer set to the residential route, other than a Bops computer, the answer also carries:

| Field | What it says |
| - | - |
| `state` | `none` (never had data), `ok`, `low` (under 0.25 GB left), `buying` (a purchase is still finishing) or `out` (none left: Chrome can't load pages until there is more). |
| `quota.counted_at` | When the network last counted the account's use. `used_bytes` and `remaining_bytes` add what the computers reported since, so they are estimates between counts. |
| `quota.this_computer_bytes` | About how much this computer has used, as it reports it. |
| `billing` | `price_cents_per_gb`, `can_buy`, `buy_blocked_reason` when it can't, `payer`, `card_available`, `buy_opens_at` with `day_limit` or `daily_data_limit`, and `daily_gb_limit` with `daily_data_limit`. No balance: [Get residential data](https://docs.orgo.ai/api-reference/account/residential-data.md) has that, for the owner. |

`billing.buy_blocked_reason` is the first of these that applies, in this order:

| `buy_blocked_reason` | Why |
| - | - |
| `unavailable` | Nobody can add data to the 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. A member reads it too. |
| `daily_data_limit` | The account was added its limit of GB for the UTC day (`daily_gb_limit`, 20 for most accounts), 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. A member reads it too. |
| `day_limit` | The account made its 10 purchases of the UTC day, card payments started included, paid or not. `buy_opens_at` says when it can buy again, the next 00:00 UTC. A member reads it too. |
| `not_owner` | Only the owner buys, signed in or with an account-wide key that has full access or Billing write. |
| `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. |

`billing.payer` is true when the caller is the owner, signed in or with an account-wide key that has full access or Billing write. `billing.card_available` is true when the owner, signed in to Orgo, can pay by card, also with `not_paying`. It is always false with an API key, which can't pay by card.

`included` is present when the owner's plan includes data each month: `gb_per_month`, `used_bytes` this UTC month, and `resets_at`, when it comes back in full. If the plan ends, pauses or switches before then, the amount follows that plan from that day. A plan on a trial includes none until the trial ends.

While data can't be added, or once the account reached its limit for the day, this month's included data not added yet can't be used. `included.waiting_bytes` says how much, and `quota.granted_bytes` and `quota.remaining_bytes` leave it out until it is added.

`computer_blocked_reason` is present when this computer can't use a residential IP whatever data the account has: `bops_computer`, `dedicated_ip`, or `paused`. Buying data doesn't help while it is set.

This call never spends.


## OpenAPI

````yaml GET /computers/{id}/residential-proxy
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:
  /computers/{id}/residential-proxy:
    get:
      tags:
        - Computers
      summary: Get residential proxy
      description: >-
        Returns whether the computer’s Chrome goes out through a residential IP,
        the last exit IP Orgo saw, and the account’s residential data, which
        belongs to the workspace owner. Only Google Chrome on the computer goes
        through the proxy. Add `check=1` to read the exit IP through the relay
        now. An IP is sticky, not fixed: it lasts up to 2 hours, and it can
        change sooner if the home connection behind it goes offline. This call
        never spends: buy data with `POST /api/billing/residential-data/buy`.
      operationId: getResidentialProxy
      parameters:
        - name: id
          in: path
          required: true
          description: Computer ID. Accepts the computer's UUID or its `instance_id`.
          schema:
            type: string
        - name: check
          in: query
          required: false
          description: >-
            `1` reads the exit IP through the relay now and adds `changed` and
            `checked_at`. Uses a few KB of data. 6 checks a minute per computer.
          schema:
            type: string
            enum:
              - '1'
      responses:
        '200':
          description: The computer's browser route and the account's data.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ResidentialProxyStatus'
                  - type: object
                    properties:
                      changed:
                        type: boolean
                        description: >-
                          With `check=1`: whether the exit IP differs from the
                          last reading.
                      checked_at:
                        type: string
                        format: date-time
                        description: 'With `check=1`: when the exit IP was read.'
              example:
                mode: residential
                proxy_on: true
                exit_ip: 73.162.44.18
                country: us
                state: ok
                quota:
                  granted_bytes: 1073741824
                  used_bytes: 262144000
                  remaining_bytes: 811597824
                  counted_at: '2026-11-10T14:05:00.000Z'
                  this_computer_bytes: 104857600
                billing:
                  price_cents_per_gb: 300
                  can_buy: true
                  buy_blocked_reason: null
                  payer: true
                  card_available: false
                included:
                  gb_per_month: 1
                  used_bytes: 262144000
                  resets_at: '2026-12-01T00:00:00.000Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            Residential IPs aren't available here, or you aren't a member of the
            computer's workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Residential proxy is not available
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: >-
            With `check=1`: the relay is off on this computer, or the IP
            couldn’t be read (`residential_not_ready`), or the computer is
            asleep (`computer_asleep`). Try again; the IP on record stands. On a
            Bops computer, or one set to your own proxy, the first two come
            without a `code`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                'off':
                  summary: Relay off
                  value:
                    error: Residential proxy is off on this computer
                    code: residential_not_ready
                unread:
                  summary: No reading
                  value:
                    error: Could not read the exit IP through the proxy. Try again
                    code: residential_not_ready
                asleep:
                  summary: Asleep
                  value:
                    error: This computer is asleep. Wake it to apply this change.
                    code: computer_asleep
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          description: The status couldn't be read.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Failed to read proxy status
components:
  schemas:
    ResidentialProxyStatus:
      type: object
      description: >-
        Which route the computer’s Chrome leaves through, its exit IP, and the
        account’s residential data. `state`, `billing`, `quota.counted_at` and
        `quota.this_computer_bytes` are present on a Linux computer set to the
        residential route, and never on a Bops computer. `included` is present
        when the owner’s plan includes data.
      properties:
        mode:
          type: string
          enum:
            - residential
            - device
            - custom
          description: >-
            The computer's browser route. `residential` is the default. `custom`
            is your own proxy, set with `POST
            /api/computers/{id}/egress/upstream` (see [Browser
            networking](/guides/browser-networking#bring-your-own-proxy)); with
            it, turning the relay on uses your proxy, not a residential IP.
        proxy_on:
          type: boolean
          description: >-
            Whether Chrome goes through the relay. It is also true on a `custom`
            route, which is not a residential IP, so read `mode` too.
        exit_ip:
          type:
            - string
            - 'null'
          description: >-
            The address websites see from Chrome, as last read. Null while the
            relay is off or before it was read.
        country:
          type: string
          description: The exit country. Only `us` for now.
        computer_blocked_reason:
          type: string
          enum:
            - bops_computer
            - dedicated_ip
            - paused
          description: >-
            Why this computer can’t use a residential IP whatever data the
            account has: a Bops computer, a dedicated IP that is on, or
            residential IPs paused for this computer. Absent when nothing stops
            it. Buying data does not help while it is set.
        state:
          type: string
          enum:
            - none
            - ok
            - low
            - buying
            - out
          description: >-
            Where the account’s data stands. `none`: the account has never had
            any. `ok`: some left. `low`: under 0.25 GB left. `buying`: a
            purchase is still finishing. `out`: none left, so Chrome can’t load
            pages until there is more. Present on a Linux computer set to the
            residential route, and never on a Bops computer.
        quota:
          type: object
          description: >-
            The workspace owner’s residential data. Every computer of the
            workspace owner draws on it.
          required:
            - granted_bytes
            - used_bytes
            - remaining_bytes
          properties:
            granted_bytes:
              type: integer
              description: >-
                All the residential data the account has had: what it bought and
                what its plan included. This month’s included data counts in
                full from the start of the month, except while it can’t be added
                (data can’t be added right now, or the account reached its limit
                for the day): then what hasn’t been added yet is left out
                (`included.waiting_bytes`). `granted_bytes` less `used_bytes` is
                what is left.
            used_bytes:
              type: integer
              description: >-
                Data used: the network’s count at `counted_at`, plus what the
                account’s computers reported since. An estimate between counts.
            remaining_bytes:
              type: integer
              description: >-
                Data left. At 0, Chrome stops loading pages and never falls back
                to the data center IP. 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, and `state` follows what has
                been added.
            counted_at:
              type:
                - string
                - 'null'
              format: date-time
              description: >-
                When the network last counted the account’s use. Null before the
                first count. Present with `state`.
            this_computer_bytes:
              type: integer
              description: >-
                About how much this computer has used, as the computer reports
                it. Present with `state`.
        billing:
          type: object
          description: >-
            Whether more data can be bought now. Present with `state`. It
            carries no balance: [Get residential
            data](/api-reference/account/residential-data) has that, for the
            owner.
          required:
            - price_cents_per_gb
            - can_buy
            - buy_blocked_reason
          properties:
            price_cents_per_gb:
              type:
                - integer
                - 'null'
              description: The price of 1 GB, in cents. Null while it is not for sale.
            can_buy:
              type: boolean
              description: The caller can buy data now.
            buy_blocked_reason:
              type:
                - string
                - 'null'
              enum:
                - unavailable
                - daily_data_limit
                - day_limit
                - not_owner
                - not_paying
                - credit_short
                - 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. A member
                reads it too. `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. A member reads
                it too. `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. A member reads it too, since the owner can’t buy
                either. `not_owner`: only the workspace owner buys data, signed
                in or with an account-wide key that has full access or Billing
                write. `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.
            payer:
              type: boolean
              description: >-
                The caller is the workspace owner, signed in or with an
                account-wide key that has full access or Billing write: the one
                who pays for this computer’s data. False for a member and a
                narrower key.
            card_available:
              type: boolean
              description: >-
                The workspace owner, signed in to Orgo, can pay for data by card
                here, also with no paid plan and no credit bought
                (`not_paying`). Always false with an API key, which can’t pay by
                card, and for anyone else. `can_buy` and `buy_blocked_reason`
                still say whether a purchase can go now.
            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.
            daily_gb_limit:
              type: integer
              description: >-
                With `daily_data_limit` only. 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.
        included:
          type: object
          description: >-
            The data the owner’s 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 until the trial ends.
          required:
            - gb_per_month
            - used_bytes
            - resets_at
          properties:
            gb_per_month:
              type: integer
              description: >-
                GB the plan includes each month: 1 on Starter, 5 on Growth, 20
                on Scale and Enterprise.
            used_bytes:
              type: integer
              description: Used of it this UTC month. An estimate between counts.
            resets_at:
              type: string
              format: date-time
              description: >-
                When it comes back in full: 00:00 UTC on the 1st of next 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.
            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, or once the
                account reached its limit for the day. It is not in
                `remaining_bytes`, and not used either. Absent while there is
                none.
      required:
        - mode
        - proxy_on
        - exit_ip
        - country
        - quota
    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.
    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
    NotFound:
      description: >-
        No computer with this id on your account. With an API key the body
        carries `code: "computer_not_found"`; signed in with a session it is
        `Desktop not found`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            api-key:
              summary: API key
              value:
                error: Computer not found (computer_not_found).
                code: computer_not_found
            session:
              summary: Signed in with a session
              value:
                error: Desktop not found
    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.