# Web Unlocker API — Anti-Bot Bypass | QuantumProxies.io

Web Unlocker API and forward proxy: residential exits, real browser TLS fingerprints, retry on a fresh IP and browser escalation when a site blocks the request.

The QuantumProxies.io Web Unlocker is built for the pages a plain HTTP client cannot get: the ones where the anti-bot layer scores the TLS handshake and the HTTP/2 settings before it reads a single header. A fetch or requests call carries its runtime's signature whatever User-Agent it sets. The unlocker fixes that at the transport layer and, unlike the Extract API, hands back the origin's raw response: any method, your own headers and body, a login or a cart held on one exit IP.

## What a web unlocker does that a proxy does not

A rotating residential proxy changes where a request comes from. It does not change what the request looks like: the TLS handshake, the HTTP/2 frame order and the header set still say Python or Node, and modern bot walls score exactly that. A web unlocker rewrites the request into one a real browser would send, retries under a different fingerprint when the origin refuses it, and switches to a real browser when the origin demands JavaScript. You keep the proxy interface; the unlocker adds the judgement.

## Real browser TLS fingerprints

Every attempt leaves under one of six browser profiles: Chrome, Firefox, Safari, Safari iOS, Edge or Brave, plus a mobile Safari option on the REST endpoint. When you pin none, retries rotate the family, so a site that has burned one handshake meets another. The identity headers are rewritten to match the profile, because a Chrome handshake carrying a Firefox User-Agent is a louder signal than either alone. Authorization, Cookie, Content-Type and custom X-* headers are forwarded verbatim, and keepHeaders sends yours as-is when you replay a captured app request.

## Retry on a fresh IP, then a real browser

A blocked GET is retried on a new residential exit with a rotated fingerprint, up to three TLS attempts within a 90-second budget. If every attempt comes back challenged, the request escalates to a headless browser that answers the JavaScript challenge and returns the rendered page. POST, PUT and DELETE never retry on an HTTP response: a 403 means the origin saw the request, and replaying it could double-submit an order or a form. Set render to html or png to start in the browser, or render to false to stay on the TLS tier.

## A block is reported, never disguised as success

Every response is classified before it reaches you. The classifier reads the headers and body that bot-defence vendors sign their pages with and names both the vendor (cloudflare, datadome, akamai and others) and the class of block: js_challenge, captcha, ip_reputation, fingerprint, geo or timeout. On the REST endpoint a still-blocked page arrives with blocked set to true and the page itself for inspection. On the forward proxy a challenge served with a 2xx becomes a 502 with the x-qp-unlocker-blocked header, while a genuine origin refusal (403, 429, 503) is relayed intact. Interactive captchas are not solved: they come back labelled captcha.

## Sessions, geo-targeting and per-site memory

Pass a country, and optionally a state or city, to exit from that market. Leave it empty and the exit country is chosen from the target's top-level domain, with the United States as the fallback. A sticky session id keeps one exit IP across calls for 3 to 1,440 minutes, so a login, a cart or a paginated listing stays on one identity. The unlocker also remembers, per domain, which tier and fingerprint family passed recently and starts there next time, and it quarantines an exit a site has just refused instead of offering it to that site again.

## Premium and Mobile tiers, prepaid per GB

The Web Unlocker runs on two exit pools: Premium on residential IPs and Mobile on 4G/5G carrier IPs, each with its own prepaid GB balance bought from the dashboard. Usage is measured in bytes moved, including retries and browser renders, and when a balance runs out the proxy answers 402 instead of failing silently. The price per GB of each tier is shown on the Web Unlocker page of the dashboard, next to the buy button. There is no subscription and no minimum term.

## Migrating an existing unlocker integration

The forward proxy accepts the control-header spellings of the two most common commercial unlockers alongside its own x-qp-* headers, so an integration usually migrates by changing the proxy host and the credentials and nothing else. Proxy mode carries targeting in the username the way the residential proxies already do: country, state, city, session, profile and tier. HTTPS through the proxy needs the interception certificate, downloadable from the API with your key. Direct mode with x-qp-url and the REST endpoint need no certificate at all.

## When to use the Web Unlocker instead of the Extract API

Use the Extract API when you want a page as Markdown, HTML or structured JSON and do not care how it was fetched. Use the Web Unlocker when you need the origin's raw response: a JSON API behind a bot wall, a POST that submits a form, a request with your own authorization header, a cookie jar you manage yourself, or an existing scraper that already speaks proxy protocol. Both live on the same account and the same residential network; only the unlocker bills from its own prepaid GB balance.

## Frequently Asked Questions

### What is a web unlocker?

A web unlocker is a service that takes a normal HTTP request and delivers it to a bot-protected site as a real browser would: from a residential IP, with a browser TLS fingerprint and matching headers, retrying on a fresh IP when blocked and using a real browser for JavaScript challenges. It returns the origin's raw response.

### How is a web unlocker different from a rotating residential proxy?

A proxy only changes the source IP. Your client's TLS handshake and header set still reveal an automated tool, and that is what modern bot walls score. The unlocker rewrites the request to match a browser, retries under another fingerprint when refused and escalates to a browser when JavaScript is demanded.

### Does the Web Unlocker solve CAPTCHAs?

It answers JavaScript challenges with a real browser and, inside a sticky session, keeps the clearance cookie for later requests to the same site. Interactive captchas that require a human are not solved: the response comes back labelled captcha, with the vendor named, so your code can decide what to do next.

### Can I send POST requests with my own headers and body?

Yes. Any HTTP method is forwarded with your body, in text or base64. Authorization, Cookie, Content-Type and custom X-* headers pass through verbatim; only the identity headers are rewritten. A POST is attempted exactly once, because replaying it after a response could double-submit a form or an order.

### How is the Web Unlocker billed?

Per GB, from a prepaid balance you buy in the dashboard for the tier you use: Premium on residential exits or Mobile on carrier exits. All bytes moved count, retries and browser renders included. When the balance is exhausted the proxy answers 402. The current price per GB is shown in the dashboard.

### What happens when a page is still blocked after every attempt?

It is never returned as a silent success. The REST endpoint sets blocked to true and includes the block class and vendor next to the page. The forward proxy turns a challenge served with a 2xx into a 502 with an x-qp-unlocker-blocked header, and relays a real 403, 429 or 503 from the origin unchanged.

### Can I keep the same IP across several requests?

Yes. Pass a session id, in the request body or in the proxy username, and every call with that id leaves from the same exit IP for 3 to 1,440 minutes. That is how a login, a shopping cart or a paginated listing stays on one identity instead of changing IP on every page.

### Do I need to install a certificate?

Only for HTTPS through the classic forward proxy, which terminates TLS to rewrite the request; the interception certificate is downloaded from the API with your key. Direct mode, where the target goes in the x-qp-url header, and the REST endpoint need no certificate at all.

### Which countries can I exit from?

The Premium tier uses the same residential network as the Residential Premium proxies, with country, state and city targeting across 200+ countries. The Mobile tier uses 4G/5G carrier IPs. When you set no country, the exit is chosen from the target's top-level domain, with the United States as the fallback.

## Sources

- [RFC 9110: HTTP Semantics — safe and idempotent methods](https://www.rfc-editor.org/rfc/rfc9110.html#name-safe-methods)
- [RFC 9110: The CONNECT method](https://www.rfc-editor.org/rfc/rfc9110.html#name-connect)
- [RFC 8446: The Transport Layer Security (TLS) Protocol Version 1.3](https://www.rfc-editor.org/rfc/rfc8446.html)
- [Proxy-Authorization header (MDN Web Docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Proxy-Authorization)
- [JA3: a method for profiling SSL/TLS clients (Salesforce, GitHub)](https://github.com/salesforce/ja3)