Make a request
POST /v1/requests runs one HTTP request through the mobile pool and returns the result as JSON.
Authentication
Send your key in the Authorization header. X-API-Key: vp_live_… works as well.
Authorization: Bearer vp_live_…Request options
The body is a JSON object. Only url is required.
| Field | Type | Meaning |
|---|---|---|
url | string | Absolute http or https URL, up to 8,000 characters. Credentials inside the URL are rejected; send an Authorization header instead. |
method | string | GET (default), POST, PUT, PATCH, DELETE, HEAD or OPTIONS. |
headers | object | Headers for the target, as name and string value. At most 60. Without a User-Agent we send one of a current mobile Chrome. |
body | string | Request body, up to 5 MB. |
body_encoding | string | Set to "base64" when body is base64-encoded binary data. Default is plain UTF-8 text. |
session | string | A name of your choice (letters, digits, _ . : -, up to 64). Requests with the same name leave through the same IP for up to 10 minutes. See IPs and sessions. |
fresh_ip | boolean | true gives the modem a new IP before the request. Costs 5 extra credits. Cannot be combined with session. |
ip_version | string | "4" (default), "6" or "auto". |
follow_redirects | boolean | Default true: up to 5 redirects are followed and count as one request. false returns the redirect response itself. |
timeout_ms | integer | How long to wait for the target, at least 1000. The upper limit and the default are your plan's timeout (30 to 120 seconds). |
These headers are managed by the connection and dropped if you send them: Host, Content-Length, Connection, Transfer-Encoding, Upgrade, TE, Trailer, Keep-Alive, Proxy-Authorization, Proxy-Connection.
Example: POST with a JSON body
curl https://api.virginproxy.com/v1/requests \
-H "Authorization: Bearer $VP_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://httpbin.org/post",
"method": "POST",
"headers": { "Content-Type": "application/json" },
"body": "{\"q\": \"shoes\"}"
}'Response
When the target answered, you get HTTP 200 from us and the target's own status inside the JSON. A target that answers 404 or 500 is still an answered request.
| Field | Meaning |
|---|---|
id | Our id for this request, e.g. req_s0F0gEspheQI7zpoNzwU. Quote it when you contact support. |
status | The target's HTTP status. |
final_url | The URL that produced the answer, after redirects. |
headers | The target's response headers, names in lower case. |
body | The response body. Text for textual content types, otherwise base64. |
body_encoding | "utf8" or "base64". Always check it before using body. |
truncated | true when the body was cut at your plan's size limit (2 to 25 MB). |
exit.ip | The public IP the target saw. |
exit.carrier | The mobile network of that IP, e.g. Vodafone or Telekom. |
exit.country | Always DE. |
bytes.up, bytes.down | Bytes sent and received on the mobile link, including TLS and headers. That is why a 33-byte body shows about 4 kB. |
duration_ms | Time from our modem starting the request to the last byte. |
cost.credits | Credits charged for this request. |
cost.credits_used, cost.credits_included | Your total for the period after this request, and what your plan includes. |
If the request could not be completed you get an error object instead. See Errors.
Binary responses
Images, PDFs and other non-text content arrive as base64 with "body_encoding": "base64". If you would rather receive the bytes directly, use raw mode.