Forward Endpoint

Solve once, then tunnel your replay through our IP using the cookie that was minted there.

Why this exists

PerimeterX, Akamai, DataDome and friends bind their cookies to the IP and TLS fingerprint that solved them. If you solve a PerimeterX cookie on VexSolver's IP and replay it from your own server, the cookie is rejected.

/api/forward closes that loop: we solve on our IP, hand you an opaque proxy_handle in the solve response, and you POST to /api/forward with that handle to replay the request from the same IP and TLS profile the cookie was minted on.

How it works

POST /api/solve — get a taskId, poll for the result. The result includes a binding.proxy_handle and a binding.ttl_sec.
POST /api/forward with that handle plus the URL you want fetched. We attach the matching cookies, route through the bound proxy (or our IP), and stream the response body back.
You can call /api/forward repeatedly for the lifetime of the handle (24 hours) and the lifetime of the cookie (typically 5–60 minutes, depends on vendor).

POST/api/forward

Costs 1 credit per call by default (some domains override). The handle must come from a recent /api/solve response.

Request body (JSON)

Field	Type	Required	Description
`proxy_handle`	string	yes	Opaque handle returned in `binding.proxy_handle` from `/api/solve`. Looks like `px-...` or the sentinel `vps-direct`.
`url`	string	yes	Target URL to fetch (must be https). Must be on the same registrable domain the cookie was minted for.
`method`	string	no	HTTP method. Defaults to `GET`. Supports `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`.
`headers`	object	no	Extra request headers. We will not override the cookie header — that one is set from the bound jar.
`body`	string	no	Request body (for POST/PUT/PATCH). Pass as a raw string; we send it byte-for-byte.
`timeout_sec`	int	no	Request timeout. Default 30, max 120.
`tls_profile`	string	no	Pin the TLS fingerprint (JA3/JA4). See profile list. Defaults to auto-pick based on the cookie's User-Agent.

Example request

# Step 1 — solve
curl -X POST https://api.vexsolver.com/api/solve \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://www.walmart.com/" }'
# → { "taskId": "abc..." }

# Step 2 — poll
curl "https://api.vexsolver.com/api/getTaskResult?taskId=abc..." \
  -H "X-API-Key: sk_live_..."
# → { "success": true, "binding": { "proxy_handle": "px-7f3a...", "ttl_sec": 86400 }, ... }

# Step 3 — replay through our IP
curl -X POST https://api.vexsolver.com/api/forward \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "proxy_handle": "px-7f3a...",
    "url":          "https://www.walmart.com/ip/Apple-AirPods/123456",
    "method":       "GET",
    "tls_profile":  "chrome_133"
  }'

Response — success

{
  "success":     true,
  "status":      200,
  "headers":     { "content-type": ["text/html; charset=utf-8"], ... },
  "body":        "<!doctype html>...",
  "egress_ip":   "85.121.148.55",
  "tls_profile": "chrome_133",
  "cookies_set": 4,
  "elapsed_ms":  2310
}

body is returned as a UTF-8 string. Binary payloads should be requested with an Accept header your client understands; we don't base64-encode.

Response — failure

{
  "success":    false,
  "error":      "handle expired or unknown",
  "elapsed_ms": 4
}

Credit is refunded automatically when success is false.

TLS profiles

Pin a specific JA3/JA4 with tls_profile. If you omit it, we auto-pick based on the User-Agent the cookie was minted with — which is usually what you want.

Value	Maps to	When to use
`chrome_133`	Chrome 133 desktop (default)	Walmart, most desktop sites
`chrome_131`	Chrome 131 desktop	Sites still on a Chrome 131 reference
`chrome_124`	Chrome 124 desktop	Legacy alignment
`chrome_120`	Chrome 120 desktop	Legacy alignment
`firefox_120`	Firefox 120	Sites that key off Firefox JA3
`safari_16`	Safari 16 desktop	macOS Safari flow
`safari_ios_17`	Safari iOS 17	iPhone mobile flow
`okhttp4`	OkHttp 4 / Android 13	Android app traffic
`zalando_android`	Zalando Android app	Zalando-style fingerprint
`nike_android`	Nike Android app	Nike-style fingerprint

Unknown values fall back to the auto-pick. The profile we actually used is returned in tls_profile on the response.

Customer flows

Three patterns customers actually use:

Pure /forward — let us handle everything. You POST the URL, we solve + tunnel + return the body. No proxy management, no cookie bookkeeping. Best for low-volume scraping.
BYOP — bring your own proxy. Pass proxy in /api/solve; the cookie binds to your proxy's IP. Replay yourself, from your own infrastructure, on that proxy. The returned proxy_handle still works against /api/forward as a convenience.
Hybrid — solve on us, replay on you, optional /forward fallback. Solve with the default flow (our IP). Use the returned cookies + user_agent directly when you don't need the IP binding. Fall back to /api/forward on the sites that strictly enforce IP binding.

The cookie is IP-bound — don't replay across networks

PerimeterX, Akamai, and similar vendors fingerprint IP + TLS. A cookie minted on our IP will be rejected on yours and vice-versa. /api/forward exists specifically to replay from the IP that minted the cookie.

Rate limits

Each proxy_handle is capped at 60 forwards/minute. Your account is capped at 600 forwards/minute across all handles. Excess returns 429 with a Retry-After header.

Handle TTL

Handles live for 24 hours. The underlying cookie usually expires sooner (5–60 minutes). When the cookie expires, the next /api/forward call returns the upstream block page — at that point, solve again to mint a fresh cookie+handle.