> ## 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 IP status

> Read whether a computer's Chrome is on a residential IP, its exit IP, the data left, and test the route with a live check.

Returns whether this computer's Google Chrome goes out through a [residential IP](https://docs.orgo.ai/guides/browser-networking.md#residential-ips), the last exit IP Orgo saw, and the account's residential data.

```bash theme={null}
curl "https://www.orgo.ai/api/computers/$COMPUTER_ID/residential-proxy" \
  -H "Authorization: Bearer $ORGO_API_KEY"
```

Replace `$COMPUTER_ID` with the computer's UUID.

## Check the exit IP now

Add `?check=1` to test the route or see whether the IP has moved. The computer reads its exit IP through the proxy, and `exit_ip` is that reading. The answer adds `changed`, which is `true` when the reading differs from the last exit IP Orgo saw, and `checked_at`.

```bash theme={null}
curl "https://www.orgo.ai/api/computers/$COMPUTER_ID/residential-proxy?check=1" \
  -H "Authorization: Bearer $ORGO_API_KEY"
```

```json theme={null}
{
  "proxy_on": true,
  "exit_ip": "203.0.113.24",
  "country": "us",
  "quota": {
    "granted_bytes": 5368709120,
    "used_bytes": 1288490188,
    "remaining_bytes": 4080218932
  },
  "changed": false,
  "checked_at": "2026-11-03T18:20:00.000Z"
}
```

You can check 6 times a minute per computer. Past that the answer is `429` with the code `rate_limited`. A check spends a few KB of the account's data.

A check answers `409` when the proxy is off, when the computer is asleep (code `computer_asleep`), or when no reading came back. The IP on record stands, so try again.

An IP lasts up to 2 hours and can change sooner, as [How long a residential IP lasts](https://docs.orgo.ai/guides/browser-networking.md#how-long-a-residential-ip-lasts) explains.

## Read the data left

`quota` is the workspace owner's residential data, shared by every computer in the account. It is DataImpulse's count as of Orgo's last hourly sync, so it can be up to an hour behind.


## 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.
  - 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:
    get:
      tags:
        - Computers
      summary: Get residential IP status
      description: >-
        Returns whether this computer's Google Chrome goes out through a
        residential IP, the last exit IP Orgo saw, and the account's residential
        data. With `?check=1`, reads the exit IP through the proxy now.
      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 proxy now and adds `changed` and
            `checked_at`. Omit it to get the last exit IP Orgo saw.
          schema:
            type: string
            enum:
              - '1'
      responses:
        '200':
          description: The status. With `?check=1`, `exit_ip` is that reading.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResidentialProxyStatus'
              examples:
                status:
                  summary: Status
                  value:
                    proxy_on: true
                    exit_ip: 203.0.113.24
                    country: us
                    quota:
                      granted_bytes: 5368709120
                      used_bytes: 1288490188
                      remaining_bytes: 4080218932
                check:
                  summary: With ?check=1
                  value:
                    proxy_on: true
                    exit_ip: 203.0.113.24
                    country: us
                    quota:
                      granted_bytes: 5368709120
                      used_bytes: 1288490188
                      remaining_bytes: 4080218932
                    changed: false
                    checked_at: '2026-11-03T18:20:00.000Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/TrialInactive'
        '403':
          description: >-
            Residential IPs are not available here, 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
                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: >-
            Only with `?check=1`. The proxy is off on this computer, the
            computer is asleep (`computer_asleep`), or no reading came back. The
            IP on record stands.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                'off':
                  summary: The proxy is off
                  value:
                    error: Residential proxy is off on this computer
                asleep:
                  summary: The computer is asleep
                  value:
                    error: This computer is asleep. Wake it to apply this change.
                    code: computer_asleep
                no-reading:
                  summary: No reading
                  value:
                    error: Could not read the exit IP through the proxy. Try again
        '429':
          description: >-
            Too many checks: 6 a minute per computer, with code `rate_limited`.
            Over a plan rate limit, `limit` names it. `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: >-
                  Too many exit IP checks on this computer. Wait, then try
                  again.
                code: rate_limited
                retry_after: 42
        '500':
          description: The status could not be read.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Failed to read proxy status
        '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.