Skip to main content

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"])