> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roundproxies.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OS Fingerprint API

> Set and check the operating system your ISP and datacenter proxies look like, through the API.

Every TCP connection carries a fingerprint of the operating system that opened it: the TTL, window size, MSS and other values in its first packet. Tools like p0f read it to guess the OS. If your browser says Windows but the connection looks like Linux, a site can notice the mismatch.

You can give your ISP and datacenter proxies the TCP/IP fingerprint of Windows, macOS, Linux, iOS or Android. The setting applies only to your own credentials, so other customers on the same IP keep theirs. New credentials, for example after you rotate them, get the same setting.

> [!NOTE]
>
> OS fingerprints are only available for ISP and datacenter proxies. For residential proxies, use [OS-targeting](https://docs.roundproxies.com/residentials/os-targeting.md).

| Method | Endpoint | Description |
| - | - | - |
| `POST` | `https://api.roundproxies.com/proxies/p0f` | Set the OS for every proxy on a plan |
| `POST` | `https://api.roundproxies.com/proxies/p0f/proxies` | Set the OS for some proxies on a plan |
| `GET` | `https://api.roundproxies.com/proxies/p0f/check` | Check which OS one proxy looks like |

## Authentication

Send your API key in the `x-api-key` header. You can find it in your [dashboard](https://app.roundproxies.com/dashboard/api).

## Set the OS for a Plan

Sets the fingerprint of every proxy on one of your ISP or datacenter plans. Proxies that have their own OS (see below) keep it. Sending the same OS again re-applies it, which is also a way to resync.

You can change a plan's OS once an hour. It is also refused for an hour after you change a proxy that follows the plan's OS.

**subscriptionId** `string` *required*

The ID of your ISP or datacenter subscription.

**os** `string` *required*

`windows`, `macos`, `linux`, `ios` or `android`. Use `none` to remove the fingerprint: the proxies then use the server's default.

> [tab] Node.js
>
> ```javascript Node.js theme={null}
> const res = await fetch("https://api.roundproxies.com/proxies/p0f", {
>   method: "POST",
>   headers: {
>     "x-api-key": process.env.RP_API_KEY,
>     "Content-Type": "application/json",
>   },
>   body: JSON.stringify({ subscriptionId: "{SUBSCRIPTION_ID}", os: "windows" }),
> });
> console.log(await res.json());
> ```

> [tab] Python
>
> ```python Python theme={null}
> import os
> import requests
>
> res = requests.post(
>     "https://api.roundproxies.com/proxies/p0f",
>     headers={"x-api-key": os.environ["RP_API_KEY"]},
>     json={"subscriptionId": "{SUBSCRIPTION_ID}", "os": "windows"},
> )
> print(res.json())
> ```

> [tab] cURL
>
> ```bash cURL theme={null}
> curl -X POST https://api.roundproxies.com/proxies/p0f \
>   -H "x-api-key: $RP_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"subscriptionId": "{SUBSCRIPTION_ID}", "os": "windows"}'
> ```

```json 200 OK theme={null}
{
  "subscriptionId": "{SUBSCRIPTION_ID}",
  "p0fOs": "windows",
  "proxies": 10,
  "applied": 10,
  "pending": 0,
  "failedProxies": []
}
```

| Field | Type | Description |
| - | - | - |
| `subscriptionId` | string | The plan you changed |
| `p0fOs` | string \| null | The plan's OS now, or `null` for none |
| `proxies` | number | How many proxies the change covered |
| `applied` | number | Changes applied right away |
| `pending` | number | Changes queued because a proxy server was unreachable. They are retried automatically. |
| `failedProxies` | string\[] | IPs that didn't take the change. Send the request again to retry them. |

## Set the OS for Some Proxies

Gives some proxies on a plan their own OS, which wins over the plan's. Use `plan` to remove it, so those proxies follow the plan's OS again. Rotating credentials keeps the setting; a replacement IP starts on the plan's OS.

Each proxy's OS can be changed once an hour, including by a change to the plan's OS. Proxies changed in the last hour are skipped.

**subscriptionId** `string` *required*

The ID of your ISP or datacenter subscription.

**ips** `string[]` *required*

The proxy IPs to change, 1 to 500 per request. They must belong to this subscription.

**os** `string` *required*

`windows`, `macos`, `linux`, `ios` or `android`. `none` uses the server's default even when the plan has an OS. `plan` follows the plan's OS again.

```bash cURL theme={null}
curl -X POST https://api.roundproxies.com/proxies/p0f/proxies \
  -H "x-api-key: $RP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subscriptionId": "{SUBSCRIPTION_ID}", "ips": ["198.51.100.7", "198.51.100.8"], "os": "macos"}'
```

The response has the same fields as above, plus:

| Field | Type | Description |
| - | - | - |
| `notFound` | string\[] | IPs you sent that are not on this subscription. If none of them are, you get a `400`. |
| `skipped` | object\[] | Proxies changed in the last hour, left as they are, with `ip` and `nextAvailableAt`. If every proxy you sent was skipped, you get a `429`. |

## Check a Proxy

Sends a request through one of your proxies, with your own credentials, to a passive fingerprinting server, and returns how its connection scores for each OS. Use it to confirm a change took effect.

**ip** `string` *required*

The IP of one of your ISP or datacenter proxies.

```bash cURL theme={null}
curl "https://api.roundproxies.com/proxies/p0f/check?ip=198.51.100.7" \
  -H "x-api-key: $RP_API_KEY"
```

```json 200 OK theme={null}
{
  "avg_score_os_class": {
    "Linux": 5.77,
    "Mac OS": 14.41,
    "Windows": 4.2,
    "iOS": 14.12
  },
  "lookup_ip": "198.51.100.7",
  "os_mismatch": null,
  "perfect_score": 20.5
}
```

| Field | Type | Description |
| - | - | - |
| `avg_score_os_class` | object | Score per OS. The highest score is the OS the connection looks like. |
| `lookup_ip` | string | The IP the fingerprinting server saw |
| `os_mismatch` | boolean \| null | Whether the server saw a mismatch, when it can tell |
| `perfect_score` | number | The highest score possible |

## Rate Limits

Each proxy's OS can be changed once an hour, whether through its plan or on its own.

| Endpoint | Limit |
| - | - |
| `POST /proxies/p0f` | Once an hour per plan; 10 requests per minute |
| `POST /proxies/p0f/proxies` | Once an hour per proxy; 30 requests per minute |
| `GET /proxies/p0f/check` | 10 requests per minute |

## Errors

| Status | Meaning |
| - | - |
| `400` | The body is invalid, or the subscription is not found, not yours, not active, or not an ISP or datacenter plan. The `message` says which. |
| `401` | The API key is missing or invalid. |
| `403` | The account is suspended. |
| `404` | Check only: the IP is not one of your active proxies. |
| `424` | Check only: the check could not complete, for example the proxy or the fingerprinting server didn't answer. The `message` has the reason. |
| `429` | Too many requests, or the OS was changed less than an hour ago. The `message` says when the next change is available. |

## Related

> [card] [ISP Basics](https://docs.roundproxies.com/isp/basics.md)
>
> Proxy format and authentication for ISP proxies.

> [card] [Datacenter Basics](https://docs.roundproxies.com/datacenter/basics.md)
>
> Proxy format and authentication for datacenter proxies.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.