Proxy Fetch API

Forwards an HTTP request through a residential IP and returns the raw response. Use this when you need a clean IP but not anti-bot bypass or JavaScript rendering. Billed by bandwidth at $2.00/GB. For protected sites, use /v1/scrape instead.

:::warning Access required Direct proxy endpoints require an active PAYG balance or subscription plan. Free-trial accounts receive 402 with code PROXY_LOCKED. During the trial, use Web Unlocker or BaaS — proxy is embedded automatically. Activate PAYG ($5 minimum top-up) or a plan to unlock. :::

POST /v1/proxy/fetch

Request

Field	Type	Default	Description
url	string	—	Required. Target URL.
method	string	GET	HTTP method.
headers	object	{}	Headers to send to the target.

curl -X POST https://api.omniscrape.io/v1/proxy/fetch \
  -H "X-API-Key: $OMNISCRAPE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.ipify.org?format=json",
    "method": "GET"
  }'

Response

{
  "success": true,
  "data": {
    "status_code": 200,
    "headers": { "content-type": "application/json" },
    "body": "{\"ip\":\"203.0.113.45\"}",
    "bandwidth": {
      "bytes": 412,
      "gb": 0.0,
      "cost": 0.0
    }
  }
}

Field	Type	Description
data.status_code	integer	Status returned by the target.
data.headers	object	Response headers from the target.
data.body	string	Raw response body.
data.bandwidth.bytes	integer	Total bytes (request + response).
data.bandwidth.cost	float	Amount billed for this request (USD).

Errors

Code	Meaning
400	url missing or blocked (SSRF protection rejects private/internal hosts).
402	Insufficient balance for proxy usage, or PROXY_LOCKED on trial accounts.
502	Upstream proxy request failed.
503	Proxy upstream not configured on this deployment.

Trial lock response:

{
  "success": false,
  "error": "direct proxy access requires PAYG or an active plan — activate PAYG or subscribe to unlock proxy URLs",
  "code": "PROXY_LOCKED"
}

Billing

$2.00 per GB of combined request and response bytes. Each response's bandwidth block shows the exact bytes and cost. Small requests round to 0. See Pricing.

Python example

import os, requests

resp = requests.post(
    "https://api.omniscrape.io/v1/proxy/fetch",
    headers={"X-API-Key": os.environ["OMNISCRAPE_KEY"]},
    json={"url": "https://api.ipify.org?format=json"},
    timeout=60,
)
data = resp.json()["data"]
print("Status:", data["status_code"])
print("Body:", data["body"])
print("Cost:", data["bandwidth"]["cost"])