> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/proxies/residential-proxies/public-api.md).

# Public API

Programmatically manage Residential Proxy sub-users, set traffic limits, and track usage statistics with the Public API.

The [**Public API**](https://residential-api.oxylabs.io/v2/docs) allows you to **manage proxy users programmatically** (via RESTful interface `https://residential-api.oxylabs.io/v2`) without using the dashboard. You can create, delete, and modify proxy sub-users, set traffic usage limits, and view current and historic traffic usage.

### Available API paths

Base Endpoint:

```
https://residential-api.oxylabs.io/v2
```

<table data-full-width="false"><thead><tr><th width="78.15625">Method</th><th width="406.92578125">Path</th><th>Description</th></tr></thead><tbody><tr><td><mark style="color:$success;">POST</mark></td><td><code>/login</code></td><td>Authenticate to get the access token (JWT).</td></tr><tr><td><mark style="color:blue;">GET</mark></td><td><code>/users/{userId}/sub-users</code></td><td>Retrieve all active sub-users</td></tr><tr><td><mark style="color:$success;">POST</mark></td><td><code>/users/{userId}/sub-users</code></td><td>Create a new sub-user.</td></tr><tr><td><mark style="color:blue;">GET</mark></td><td><code>/users/{userId}/sub-users/{subUserId}</code></td><td>Retrieve traffic usage statistics for a specific sub-user.</td></tr><tr><td><mark style="color:$primary;">PATCH</mark></td><td><code>/users/{userId}/sub-users/{subUserId}</code></td><td>Modify a sub-user.</td></tr><tr><td><mark style="color:red;">DELETE</mark></td><td><code>/users/{userId}/sub-users/{subUserId}</code></td><td>Delete a sub-user.</td></tr><tr><td><mark style="color:blue;">GET</mark></td><td><code>/users/{userId}/sub-users/{subUserId}/target-stats</code></td><td>Get sub-user traffic usage per target domain (last 30 days, requires specific date).</td></tr><tr><td><mark style="color:blue;">GET</mark></td><td><code>/users/{userId}/client-stats</code></td><td>Retrieve total traffic usage for the current month.</td></tr></tbody></table>

### Authentication & usage flow

All API requests (except `/login`) require a JSON Web Token (JWT) passed in the `Authorization: Bearer {token}` HTTP header.

{% hint style="info" %}
The `login` endpoint requires your Main User credentials (the first sub-user in your dashboard users list). If you recently changed your main user password, use the original password or [contact support](mailto:support@oxylabs.io).&#x20;
{% endhint %}

{% hint style="warning" %}
The generated JWT access token expires in 1 hour. After expiration, you must request a new token via `POST /login`.
{% endhint %}

{% stepper %}
{% step %}

### Generate JWT access token

Authenticate via `POST /login` using HTTP Basic Authentication with your main user credentials (encoded in base64).

```bash
curl -X "POST" \
  "https://residential-api.oxylabs.io/v2/login" \
  -H "accept: application/json" \
  -u "MAIN_USERNAME:MAIN_PASSWORD"
```

The response includes two key values:

```json
{
  "user_id": "00000000-0000-0000-0000-000000000000",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

Save the returned `user_id` and `token` for all subsequent requests.
{% endstep %}

{% step %}

### Make authenticated API requests

Include the JWT in the `Authorization: Bearer {token}` header and pass your `user_id` in the request path to query the API to manage users and check statistics.

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X "GET" \
  "https://residential-api.oxylabs.io/v2/users/YOUR_USER_ID/client-stats" \
  -H "accept: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

user_id = "00000000-0000-0000-0000-000000000000"
jwt_token = "YOUR_JWT_TOKEN"

url = f"https://residential-api.oxylabs.io/v2/users/{user_id}/client-stats"
headers = {
    "accept": "application/json",
    "Authorization": f"Bearer {jwt_token}"
}

response = requests.get(url, headers=headers)
print(response.json())
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const axios = require('axios');

const userId = '00000000-0000-0000-0000-000000000000';
const jwtToken = 'YOUR_JWT_TOKEN';

axios.get(`https://residential-api.oxylabs.io/v2/users/${userId}/client-stats`, {
  headers: {
    'accept': 'application/json',
    'Authorization': `Bearer ${jwtToken}`
  }
})
.then(response => console.log(response.data))
.catch(error => console.error(error));
```

{% endtab %}
{% endtabs %}

#### Output sample

```json
{
  "traffic": 1.2354839,
  "date_from": "2026-09-01",
  "date_to": "2026-09-14"
}
```

{% endstep %}
{% endstepper %}

### Backconnect entry setup (CNAME)

To route proxy traffic through your custom domain name instead of `pr.oxylabs.io`, configure a DNS `CNAME` record in your DNS provider manager.

1. Create a new `CNAME` record in your DNS provider (e.g., Cloudflare, Route 53).
2. Set the hostname/subdomain (e.g., `entry.yourdomain.com`) to target `pr.oxylabs.io`.
3. Use your custom domain name in place of `pr.oxylabs.io` across all proxy request connection strings.

![Backconnect](https://3826932121-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2Fgit-blob-9d15ff608e52a76e6d288eb45c3bd648ddf970ef%2Fcname.jpg?alt=media)

For more information, please contact [**Customer support**](mailto:support@oxylabs.io) or your account manager.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.oxylabs.io/products/proxies/residential-proxies/public-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.