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.

FieldTypeMeaning
urlstringAbsolute http or https URL, up to 8,000 characters. Credentials inside the URL are rejected; send an Authorization header instead.
methodstringGET (default), POST, PUT, PATCH, DELETE, HEAD or OPTIONS.
headersobjectHeaders for the target, as name and string value. At most 60. Without a User-Agent we send one of a current mobile Chrome.
bodystringRequest body, up to 5 MB.
body_encodingstringSet to "base64" when body is base64-encoded binary data. Default is plain UTF-8 text.
sessionstringA 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_ipbooleantrue gives the modem a new IP before the request. Costs 5 extra credits. Cannot be combined with session.
ip_versionstring"4" (default), "6" or "auto".
follow_redirectsbooleanDefault true: up to 5 redirects are followed and count as one request. false returns the redirect response itself.
timeout_msintegerHow 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.

FieldMeaning
idOur id for this request, e.g. req_s0F0gEspheQI7zpoNzwU. Quote it when you contact support.
statusThe target's HTTP status.
final_urlThe URL that produced the answer, after redirects.
headersThe target's response headers, names in lower case.
bodyThe response body. Text for textual content types, otherwise base64.
body_encoding"utf8" or "base64". Always check it before using body.
truncatedtrue when the body was cut at your plan's size limit (2 to 25 MB).
exit.ipThe public IP the target saw.
exit.carrierThe mobile network of that IP, e.g. Vodafone or Telekom.
exit.countryAlways DE.
bytes.up, bytes.downBytes sent and received on the mobile link, including TLS and headers. That is why a 33-byte body shows about 4 kB.
duration_msTime from our modem starting the request to the last byte.
cost.creditsCredits charged for this request.
cost.credits_used, cost.credits_includedYour 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.