> ## 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. # Turn a residential IP on or off > Route a computer's Chrome through a home internet connection, get a new IP, or go back to the data center address. Sends this computer's Google Chrome out through a home internet connection instead of the data center, moves it to a new IP, or turns that off. [Browser networking](https://docs.orgo.ai/guides/browser-networking.md#residential-ips) covers what a residential IP is for and which sites fail on one. > [!NOTE] > > This works on Linux computers only. Only Google Chrome goes through the proxy: the terminal, other browsers and agent API calls keep the data center address. ## Turn on a residential IP ```bash theme={null} curl -X POST "https://www.orgo.ai/api/computers/$COMPUTER_ID/residential-proxy" \ -H "Authorization: Bearer $ORGO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"enabled": true}' ``` Replace `$COMPUTER_ID` with the computer's UUID. The computer must be running. ```json theme={null} { "proxy_on": true, "exit_ip": "203.0.113.24", "country": "us", "quota": { "granted_bytes": 5368709120, "used_bytes": 1288490188, "remaining_bytes": 4080218932 } } ``` Turning it on restarts Chrome once, so open tabs close. Residential data belongs to the workspace owner, and accounts start with none. Until the account has data, this answers `409` with `Residential proxy is turned off for this account`. To ask for data, email [contact@orgo.ai](mailto:contact@orgo.ai). ## Get a new IP ```bash theme={null} curl -X POST "https://www.orgo.ai/api/computers/$COMPUTER_ID/residential-proxy" \ -H "Authorization: Bearer $ORGO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"enabled": true, "new_ip": true}' ``` When the proxy is already on, Chrome keeps running and open connections drop. When it is off, this turns it on with a new IP and restarts Chrome. A computer using your own proxy or device keeps its address: `new_ip` gets no new IP there. ### New IP limits | Limit | Count | | - | - | | Per computer | One a minute and 30 a day | | Per account | 200 a day | A day ends at 00:00 UTC, and an attempt that fails still counts. Past a limit the answer is `429` with a `Retry-After` header: ```json theme={null} { "error": "A computer can get one new IP every 60 seconds. Try again in 42 seconds.", "code": "residential_new_ip_limited", "retry_after": 42 } ``` ## Turn off a residential IP ```bash theme={null} curl -X POST "https://www.orgo.ai/api/computers/$COMPUTER_ID/residential-proxy" \ -H "Authorization: Bearer $ORGO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"enabled": false}' ``` Chrome goes back to the data center address and restarts if it is open. On an asleep computer this answers `"proxy_on": false` at once, and the proxy comes off when the computer wakes. ## Choose a country Residential IPs are US only for now. `country` takes `us`, and leaving it out means the same. Any other value answers `400`: ```json theme={null} { "error": "Only US IPs are available right now. To ask about other countries, email contact@orgo.ai.", "code": "residential_country_unavailable" } ``` To ask about another country, email [contact@orgo.ai](mailto:contact@orgo.ai). ## When a site fails Some sites can't be reached through a residential IP, and Chrome shows `ERR_TUNNEL_CONNECTION_FAILED` for them. They fail rather than falling back to the data center address. Orgo blocks ticketing, video and music streaming, gambling, torrent and speed test sites. DataImpulse, the network behind residential IPs, blocks banks, payment sites and government sites itself. Webmail in the browser works. [Blocked sites by category](https://docs.orgo.ai/guides/browser-networking.md#blocked-sites-by-category) has the detail. ## When the data runs out The computers using it go back to the data center address, which restarts Chrome, and turning it on answers `409` with `Residential data quota is used up for this account`. Read what is left with [Get residential IP status](https://docs.orgo.ai/api-reference/computers/residential-proxy-get.md). ## When Orgo refuses a change Each of these answers `409` and changes nothing: | `error` | What it means | | - | - | | `Residential proxy is turned off for this account` | The account has no residential data. | | `Residential data quota is used up for this account` | The account's data is used up. | | `Residential proxy is paused for this computer` or `for this account` | Orgo has paused residential IPs here. Email [contact@orgo.ai](mailto:contact@orgo.ai). | | `New IP is paused for this computer` | Orgo has paused New IP here. The current IP keeps working. | | `Residential data is not available right now. Try again later` | Orgo can't add data right now. Try again later. | | `This computer has a dedicated IP. Turn that off before routing its browser elsewhere.` | The computer has a dedicated IP. | | `This computer is asleep. Wake it to apply this change.` | Code `computer_asleep`. Resume or start the computer. | ## 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. - 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: 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. paths: /computers/{id}/residential-proxy: post: tags: - Computers summary: Turn a residential IP on or off description: >- Turns a residential IP on or off for this computer's Google Chrome, or moves it to a new IP. Linux computers only. The data belongs to the workspace owner. 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 and keeps the sticky IP. `false` turns it off. new_ip: type: boolean default: false description: >- With `enabled: true`, moves to a different IP. Ignored with `enabled: false`. country: type: string enum: - us description: >- The exit country. Only `us` for now, and leaving it out means the same. To ask about other countries, email contact@orgo.ai. examples: 'on': summary: Turn it on value: enabled: true new-ip: summary: Get a new IP value: enabled: true new_ip: true 'off': summary: Turn it off value: enabled: false responses: '200': description: >- The status after the change. `exit_ip` is `null` if Orgo could not read one. content: application/json: schema: $ref: '#/components/schemas/ResidentialProxyStatus' example: proxy_on: true exit_ip: 203.0.113.24 country: us quota: granted_bytes: 5368709120 used_bytes: 1288490188 remaining_bytes: 4080218932 '400': description: >- `enabled` is missing or not a boolean, `country` is not `us`, or the computer is not a Linux computer Orgo runs as a virtual machine. content: application/json: schema: $ref: '#/components/schemas/Error' examples: enabled: summary: enabled is missing value: error: enabled (boolean) is required country: summary: Another 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 virtual machine value: error: >- Residential proxy isn’t available for this computer. It works only on Linux computers that Orgo runs as virtual machines. code: residential_proxy_unsupported '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/TrialInactive' '403': description: >- Residential IPs are not available here, the account is an unclaimed agent account, you have view-only access, you are not the owner or a member of the workspace, or the API key is scoped to another workspace. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not-available: summary: Not available here value: error: Residential proxy is not available unclaimed: 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 no-access: summary: Not in the workspace value: error: You do not have access to this workspace. scoped-key: summary: Key for another workspace value: error: >- This API key cannot access this workspace (workspace_scope_mismatch). '404': $ref: '#/components/responses/NotFound' '409': description: >- Nothing changed. The account has no data or has used it, residential IPs or New IP are paused for this computer or account, the computer has a dedicated IP, it is asleep (`computer_asleep`), or it is not ready. content: application/json: schema: $ref: '#/components/schemas/Error' examples: no-data: summary: No residential data on the account value: error: Residential proxy is turned off for this account used-up: summary: Data used up value: error: Residential data quota is used up for this account paused: summary: Paused value: error: Residential proxy is paused for this computer new-ip-paused: summary: New IP paused value: error: New IP is paused for this computer unavailable: summary: Not available right now value: error: >- Residential data is not available right now. Try again later dedicated-ip: summary: Dedicated IP value: error: >- This computer has a dedicated IP. Turn that off before routing its browser elsewhere. asleep: summary: The computer is asleep value: error: This computer is asleep. Wake it to apply this change. code: computer_asleep not-ready: summary: Not ready value: error: Could not configure the proxy on this computer '429': description: >- Over a New IP limit (`residential_new_ip_limited`), or a plan rate limit (`rate_limited`). `retry_after` and `Retry-After` say how many seconds to wait. headers: Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: >- A computer can get one new IP every 60 seconds. Try again in 42 seconds. code: residential_new_ip_limited retry_after: 42 '500': description: The change failed for a reason not listed here. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Failed to update proxy '503': $ref: '#/components/responses/AuthUnavailable' components: schemas: ResidentialProxyStatus: type: object description: A computer's residential IP and the account's residential data. required: - proxy_on - exit_ip - country - quota properties: proxy_on: type: boolean description: '`true` while this computer''s Chrome goes through the proxy.' exit_ip: type: - string - 'null' description: >- The last exit IP Orgo saw. `null` while the proxy is off, or if Orgo could not read one. country: type: string description: 'The exit country: `us`.' quota: type: object description: >- The workspace owner's residential data, shared by every computer in the account. DataImpulse's count as of Orgo's last hourly sync, so it can be up to an hour behind. required: - granted_bytes - used_bytes - remaining_bytes properties: granted_bytes: type: integer description: The data the account has. used_bytes: type: integer description: The data used so far. remaining_bytes: type: integer description: '`granted_bytes` less `used_bytes`, and never below 0.' changed: type: boolean description: >- Only with `?check=1`: this reading differs from the last exit IP Orgo saw. checked_at: type: string format: date-time description: 'Only with `?check=1`: when it was read.' 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: $ref: '#/components/schemas/Error' examples: invalid-key: summary: The key is not one of yours value: error: Invalid API key no-credential: summary: No key and no session value: error: Authentication required TrialInactive: description: >- The computer is a free trial computer whose trial is no longer active, or it is paid for by its own subscription or dedicated purchase and that payment has lapsed. content: application/json: schema: $ref: '#/components/schemas/Error' examples: trial: summary: Trial no longer active value: error: Choose a plan to continue. payment: summary: The computer's own payment has lapsed value: error: Manage this computer’s payment in Account → Usage. 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 AuthUnavailable: description: >- Orgo could not verify the credential because of a server-side fault, such as a database outage. Retry after `Retry-After`. Do not rotate the key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: >- Service temporarily unavailable. The database is not accepting requests. Retry shortly. headers: Retry-After: description: Seconds to wait before retrying. Always `5`. schema: type: string example: '5' headers: RetryAfter: description: Seconds to wait before asking again. schema: type: integer minimum: 1 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.