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

# Set residential proxy

> Turn the residential IP on or off for a computer's Chrome, or get a new IP.

Turns the residential proxy on or off for a running Linux computer, or gets a new IP. See [Residential IP](https://docs.orgo.ai/guides/browser-networking.md#residential-ip).

* `{"enabled": true}` turns it on and keeps the computer's sticky IP. It lasts up to 2 hours, and changes sooner if the home connection behind it goes offline.
* `{"enabled": true, "new_ip": true}` gets a new IP.
* `{"enabled": false}` turns it off. Chrome goes out from the data center again.

Turning it on or off restarts Chrome. Getting a new IP while it's on doesn't. Only Chrome goes through it.

A computer can get one new IP a minute and 30 a day, and an account 200 a day, reset at 00:00 UTC. Past a limit the call answers `429` with `retry_after`.

## Data

The computer draws on the workspace owner's residential data: what the owner's plan includes each month (1 GB on Starter, 5 GB on Growth, 20 GB on Scale and Enterprise), used first, then data bought at \$3 per GB from credits. This call never buys. This month's included data that is waiting to be added (`included.waiting_bytes` in [Get residential proxy](https://docs.orgo.ai/api-reference/computers/residential-proxy-get.md)) isn't data left here.

Up to 20 GB can be added to the account a UTC day, every way together: included data as it is used, purchases and card payments. The limit is on adding data, not using it: data the account already has can still be used, but nothing more is added until 00:00 UTC.

With no data left, turning it on changes nothing and answers the first of these that applies:

| Status | `code` | When |
| - | - | - |
| `409` | `RESIDENTIAL_PURCHASE_IN_PROGRESS` | A purchase is still finishing. Try again in a minute. |
| `503` | `RESIDENTIAL_DATA_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. Anyone who asks gets it, a member too. Buying, paying or asking the owner won't help. Nothing was charged. Try again later. |
| `429` | `RESIDENTIAL_DAILY_LIMIT` | The account was added its limit of GB for the UTC day (20 GB for most accounts), so nothing more can be added until 00:00 UTC, by anyone. It carries `retry_after`, `buy_opens_at` and `daily_gb_limit`. A member reads it too, in words that say it is the workspace owner's account. |
| `429` | `rate_limited` | The account's 10 purchases of the UTC day are used, so nothing can be bought until 00:00 UTC. It carries `retry_after` and `buy_opens_at`, on a free account as on a paying one. A member reads it too, in words that say the owner reached the limit. |
| `402` | `RESIDENTIAL_DATA_NEEDED` | To the owner, signed in or with an account-wide key that has full access or Billing write, it carries `price_cents`, `available_cents`, `can_buy` and a `next` call: [Buy residential data](https://docs.orgo.ai/api-reference/account/buy-residential-data.md), or adding credit when the credits are short. Anyone else is told to ask the owner, also when the owner's account isn't a paying one. |
| `403` | `PLAN_REQUIRED` | To the owner only: the account has no paid plan and no credit bought. Starting credit alone can't buy residential data. Pay by card in Orgo, add credit, or pick a plan. |

All but `rate_limited` also carry `retryable` and `docs_url`.

## Other refusals

A `409` changes nothing and names why in `code`:

| `code` | Why |
| - | - |
| `residential_paused` | Residential IPs are paused for this computer or the account. |
| `residential_new_ip_paused` | New IP is paused for this computer. |
| `residential_dedicated_ip` | The computer has a dedicated IP. Turn that off first. |
| `residential_unavailable` | Residential data can't be added right now. Try again later. |
| `residential_not_ready` | The account's data or the computer isn't ready. Try again. |
| `residential_daily_limit` | Where data isn't for sale: the account has no data left and was added its limit of GB for the UTC day. It carries `retry_after`, `buy_opens_at` and `daily_gb_limit`, with `Retry-After`. More can be added from 00:00 UTC. |
| `computer_asleep` | The computer is asleep. Wake it first. |

A Bops computer can't use a residential IP and answers `409` with no `code`. On a computer set to [your own proxy](https://docs.orgo.ai/guides/browser-networking.md#bring-your-own-proxy), these refusals other than `computer_asleep` come without a `code`.


## OpenAPI

````yaml POST /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:
    post:
      tags:
        - Computers
      summary: Set residential proxy
      description: >-
        Turns the residential proxy on or off for a Linux computer’s Chrome, or
        gets a new IP. The computer must be running. Turning it on or off
        restarts Chrome; getting a new IP while it’s on doesn’t.


        It draws on the workspace owner’s residential data: what the owner’s
        plan includes each month, used first, then data bought. This call never
        spends. With no data left it answers `402` `RESIDENTIAL_DATA_NEEDED`,
        and the owner buys more with `POST /api/billing/residential-data/buy`.
        Once the account was added its limit of GB for the UTC day (20 for most
        accounts, every way together), it answers `429`
        `RESIDENTIAL_DAILY_LIMIT` with `buy_opens_at` and `daily_gb_limit`
        instead, to anyone who asks; where data isn’t for sale that is a `409`
        `residential_daily_limit`. Once the day’s purchases are used it answers
        `429` `rate_limited` with `buy_opens_at`. Where nobody could add data to
        the account, anyone who asks gets `503` `RESIDENTIAL_DATA_UNAVAILABLE`.
        This month’s included data that is waiting to be added
        (`included.waiting_bytes` on the status) isn’t data left here either.


        US IPs only for now: `country` takes `us` and nothing else. To ask about
        other countries, email contact@orgo.ai.


        Some sites can’t be reached through a residential IP: ticketing, video
        and music streaming, gambling, torrents and speed tests, along with what
        the network blocks itself, such as banks, government sites and mail
        ports. Chrome shows ERR_TUNNEL_CONNECTION_FAILED for them. Webmail in
        the browser works. Orgo records the sites a computer reaches this way
        (the domain, never a path or content), per computer and IP, for 30 days.
      operationId: setResidentialProxy
      parameters:
        - name: id
          in: path
          required: true
          description: Computer ID. Accepts the computer's UUID or its `instance_id`.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - enabled
              properties:
                enabled:
                  type: boolean
                  description: >-
                    `true` turns it on, `false` turns it off and Chrome goes out
                    from the data center again.
                new_ip:
                  type: boolean
                  default: false
                  description: >-
                    With `enabled: true`, get a new residential IP. Without it,
                    the computer keeps its sticky IP: it lasts up to 2 hours,
                    and changes sooner if the home connection behind it goes
                    offline.
                country:
                  type: string
                  enum:
                    - us
                  description: >-
                    The exit country. Only `us` for now; any other value is
                    `400`.
            examples:
              'on':
                summary: Turn on
                value:
                  enabled: true
              new-ip:
                summary: Get a new IP
                value:
                  enabled: true
                  new_ip: true
              'off':
                summary: Turn off
                value:
                  enabled: false
      responses:
        '200':
          description: The computer's browser route after the change.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResidentialProxyStatus'
              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'
        '400':
          description: >-
            A malformed body, a country other than `us`, or a computer that
            isn't a Linux computer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing:
                  summary: No `enabled`
                  value:
                    error: enabled (boolean) is required
                country:
                  summary: Country
                  value:
                    error: >-
                      Only US IPs are available right now. To ask about other
                      countries, email contact@orgo.ai.
                    code: residential_country_unavailable
                unsupported:
                  summary: Not a Linux computer
                  value:
                    error: Residential proxy isn’t supported on Windows computers.
                    code: residential_proxy_unsupported
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: >-
            The account has no residential data left
            (`RESIDENTIAL_DATA_NEEDED`). Nothing changed and nothing was spent.
            To the workspace owner, signed in or with an account-wide key that
            has full access or Billing write, it carries `price_cents`,
            `available_cents` and `can_buy`, and `next`: the call that buys 1
            GB, or, when the credits don’t cover it (`buy_blocked_reason:
            "credit_short"`), the call that adds credit, with `add_credit_url`.
            To anyone else it says to ask the workspace owner, with no price,
            also when the owner’s account isn’t a paying one. It never comes
            where the owner’s buy would be refused anyway: that is the `503`, or
            the `429` once the account’s GB or purchases of the day are used.
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                  - code
                properties:
                  error:
                    type: string
                  code:
                    type: string
                    enum:
                      - RESIDENTIAL_DATA_NEEDED
                  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. To the owner only.
                  available_cents:
                    type:
                      - integer
                      - 'null'
                    description: The account’s credits, in cents. To the owner only.
                  can_buy:
                    type: boolean
                    description: To the owner only.
                  buy_blocked_reason:
                    type: string
                    enum:
                      - credit_short
                    description: Present when the credits don’t cover 1 GB.
                  add_credit_url:
                    type: string
                    format: uri
                    description: >-
                      With `credit_short`: the page a person opens to add
                      credit.
              examples:
                owner:
                  summary: To the owner
                  value:
                    error: >-
                      This account has no residential data. It costs $3.00 per
                      GB from your Orgo credits. Buy some, then turn this on
                      again.
                    code: RESIDENTIAL_DATA_NEEDED
                    price_cents: 300
                    available_cents: 1250
                    can_buy: true
                    retryable: false
                    next:
                      method: POST
                      url: https://www.orgo.ai/api/billing/residential-data/buy
                      body:
                        gb: 1
                        expected_price_cents: 300
                      why: Spends $3.00 of Orgo credits. Ask your human first.
                    docs_url: https://www.orgo.ai/pricing.md#residential-ip-data
                member:
                  summary: To a member or a narrower key
                  value:
                    error: >-
                      This account has no residential data. The workspace owner
                      can buy more.
                    code: RESIDENTIAL_DATA_NEEDED
                    retryable: false
                    docs_url: https://www.orgo.ai/pricing.md#residential-ip-data
        '403':
          description: >-
            Residential IPs aren’t available here, the account is an unclaimed
            agent account, you can’t change this computer, or, to the workspace
            owner signed in or with an account-wide key, the account has no data
            left and is not a paying account (`PLAN_REQUIRED`: no paid plan and
            no credit bought; starting credit alone can’t buy residential data).
            Where nobody could add data it is the `503` instead, and once the
            account’s GB or purchases of the day are used the `429`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                'off':
                  summary: Not available
                  value:
                    error: Residential proxy is not available
                agent:
                  summary: Unclaimed agent account
                  value:
                    error: >-
                      Unclaimed agent accounts can’t use the residential proxy.
                      Ask your person to claim this account with the claim link
                      from signup (a new one: POST /api/v1/agents/claim).
                    code: agent_account_unclaimed
                plan-required:
                  summary: No data, and 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
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: >-
            Nothing changed. A purchase for the account is still finishing
            (`RESIDENTIAL_PURCHASE_IN_PROGRESS`, with `retryable`, `next` and
            `docs_url`). Residential IPs are paused for this computer or the
            account (`residential_paused`), or New IP is
            (`residential_new_ip_paused`). The computer has a dedicated IP
            (`residential_dedicated_ip`). Residential data can’t be added right
            now (`residential_unavailable`). The account’s data or the computer
            isn’t ready (`residential_not_ready`). Where data isn’t for sale,
            the account has no data left and was added its limit of GB for the
            UTC day (`residential_daily_limit`, with `retry_after`,
            `buy_opens_at`, `daily_gb_limit` and `Retry-After`): more can be
            added from 00:00 UTC. The computer is asleep (`computer_asleep`). On
            a computer set to your own proxy, all but `computer_asleep` come
            without a `code`. A Bops computer on the residential route always
            answers `409`, with no `code`.
          headers:
            Retry-After:
              description: 'With `residential_daily_limit`: seconds until 00:00 UTC.'
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
                  code:
                    type: string
                    enum:
                      - RESIDENTIAL_PURCHASE_IN_PROGRESS
                      - residential_paused
                      - residential_new_ip_paused
                      - residential_dedicated_ip
                      - residential_unavailable
                      - residential_not_ready
                      - residential_daily_limit
                      - computer_asleep
                  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
                  retry_after:
                    type: integer
                    description: 'With `residential_daily_limit`: seconds to wait.'
                  buy_opens_at:
                    type: string
                    format: date-time
                    description: >-
                      With `residential_daily_limit`: when more can be added,
                      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.
              examples:
                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
                paused:
                  summary: Paused
                  value:
                    error: Residential proxy is paused for this computer
                    code: residential_paused
                new-ip-paused:
                  summary: New IP paused
                  value:
                    error: New IP is paused for this computer
                    code: residential_new_ip_paused
                dedicated-ip:
                  summary: Dedicated IP
                  value:
                    error: >-
                      This computer has a dedicated IP. Turn that off before
                      routing its browser elsewhere.
                    code: residential_dedicated_ip
                unavailable:
                  summary: Data can’t be added now
                  value:
                    error: >-
                      Residential data can't be added right now. You were not
                      charged.
                    code: residential_unavailable
                not-ready:
                  summary: Not ready
                  value:
                    error: >-
                      Residential data is not set up for this account yet. Try
                      again
                    code: residential_not_ready
                daily-limit:
                  summary: The day’s GB are used, where data isn’t for sale
                  value:
                    error: >-
                      This account has no residential data, and it reached its
                      limit of 20 GB a day. More can be added after 00:00 UTC.
                    code: residential_daily_limit
                    retry_after: 3600
                    buy_opens_at: '2026-11-11T00:00:00.000Z'
                    daily_gb_limit: 20
                bops:
                  summary: Bops computer
                  value:
                    error: Residential proxy is not available on Bops computers
                asleep:
                  summary: Asleep
                  value:
                    error: This computer is asleep. Wake it to apply this change.
                    code: computer_asleep
        '429':
          description: >-
            Nothing changed. Too many new IPs (`residential_new_ip_limited`):
            one a minute per computer, 30 a day per computer, 200 a day per
            account. Or the account has no data left and was added its limit of
            GB for the UTC day, so nothing more can be added until 00:00 UTC, by
            anyone (`RESIDENTIAL_DAILY_LIMIT`, with `buy_opens_at`,
            `daily_gb_limit`, `retryable`, `next` and `docs_url`), to the owner
            and a member alike, a member in words that say it is the workspace
            owner’s account. Or the account has no data left and its 10
            purchases of the UTC day are used, so a buy or a card payment would
            be refused until 00:00 UTC (`rate_limited`, with `buy_opens_at`), on
            a free account as on a paying one, to the owner and a member alike.
            Days reset at 00:00 UTC. `retry_after` and `Retry-After` say how
            many seconds to wait.
          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:
                      - residential_new_ip_limited
                      - rate_limited
                      - RESIDENTIAL_DAILY_LIMIT
                  retry_after:
                    type: integer
                    description: Seconds to wait.
                  buy_opens_at:
                    type: string
                    format: date-time
                    description: >-
                      With `rate_limited` or `RESIDENTIAL_DAILY_LIMIT`: 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:
                new-ip:
                  summary: New IP limit
                  value:
                    error: >-
                      A computer can get one new IP every 60 seconds. Try again
                      in 42 seconds.
                    code: residential_new_ip_limited
                    retry_after: 42
                daily-data-limit:
                  summary: No data, and the day’s GB are used
                  value:
                    error: >-
                      This account has no residential data, and it reached its
                      limit of 20 GB a day. More can be added after 00:00 UTC.
                    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
                daily-data-limit-member:
                  summary: The same, to a member
                  value:
                    error: >-
                      The workspace owner's account has no residential data, and
                      it reached its limit of 20 GB a day. More can be added
                      after 00:00 UTC.
                    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
                day-limit:
                  summary: No data, and the day’s purchases are used
                  value:
                    error: >-
                      This account has no residential data, and it reached its
                      limit of 10 purchases today. Card payments you started
                      count too. You can buy again after 00:00 UTC.
                    code: rate_limited
                    retry_after: 3600
                    buy_opens_at: '2026-11-11T00:00:00.000Z'
                day-limit-member:
                  summary: The same, to a member
                  value:
                    error: >-
                      This account has no residential data, and the workspace
                      owner reached the limit of 10 purchases today. The owner
                      can buy again after 00:00 UTC.
                    code: rate_limited
                    retry_after: 3600
                    buy_opens_at: '2026-11-11T00:00:00.000Z'
        '500':
          description: The change failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Failed to update proxy
        '503':
          description: >-
            The account has no data left, and nobody can add data to it right
            now (`RESIDENTIAL_DATA_UNAVAILABLE`): 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.
            Buying, paying or asking the owner won’t help. It comes before
            `PLAN_REQUIRED`, the `402` and the `429`, to anyone who asks, a
            member included. Nothing changed and nothing was spent. Try again
            later.
          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:
    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.
  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
  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.