ProxyField Scraper API Documentation

The APIs below are designed and priced, and they are not open for calls yet. Use this page to plan an integration; ask sales for access and the go-live date. Every API runs on ProxyField's own pool, is billed on successful results only, and is paid from the same crypto balance as your proxies.

The lower price in each row is the volume price: it applies from 10,000 successful results in one purchase.

Send your API key in the Authorization header of every request:

Authorization: Bearer <api_key>

The header is the only place the key goes: the API takes no key in the query string, because URLs end up in logs. Your key is created in the ProxyField dashboard once sales opens access. A missing or unknown key returns 401 invalid_api_key, which is not billed.

All endpoints live under https://api.proxyfield.io/v1. A version only grows: new optional parameters, new response fields and new values of a field can appear within v1, so your code should ignore fields it does not know. Removing or renaming anything needs v2.

• Every endpoint takes POST with a JSON body (Content-Type: application/json, UTF-8).
• An unknown parameter returns 400 invalid_parameter, so a typo does not pass silently. null means "use the default".
• A parameter that only works with another one, such as wait_for without render: true, returns 400 unsupported_combination.
• Two parameters work on every endpoint:

Parsed endpoints return one JSON object with three parts: metadata, parameters (your request with the defaults filled in) and the API's own blocks.

Field rules:

• Every field is always present. A block that is not on the page comes back as null or [], never missing.
• Names are snake_case. Links are url, every link has its domain, and every list item has a 1-based position.
• AI answers share one citation shape: citations[] of {position, title, url, domain, snippet}. Text blocks point to them with citations: [1, 2].

Response headers, on every response including errors:

Every API accepts the proxy pool's 195+ countries.

• Google endpoints use Google's own names: gl (country of the results, a two-letter code), hl (interface language), google_domain, and location (a canonical name such as Austin,Texas,United States). The request leaves from an IP in the gl country. Find canonical names with GET /v1/google/locations?q=austin&gl=us&limit=20, which returns locations[] of {canonical_name, name, type, country_code} and is not billed.
• The other endpoints use country, a two-letter code in lowercase.
• A country the API does not accept returns 400 unsupported_country. Postal-code locations are not part of the first version.

One request returns one Google results page, with the AI Overview, People Also Ask and the local pack parsed.

There is no num parameter: Google stopped serving 100 results on one page in September 2025, so a deeper rank check reads several pages, each one billed. When Google loads the AI Overview after the page, the API fetches it in the same request at no extra charge; ai_overview.status is present, absent or error. People Also Ask is returned as the page shows it, never expanded by clicking.

# The request the Google SERP API takes (access through Contact sales)
curl https://api.proxyfield.io/v1/google/search \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"q": "espresso machine", "gl": "us", "hl": "en", "location": "Austin,Texas,United States"}'

{
  "metadata": {"id": "req_7f3c9a1e52d84b0c", "api": "google_search", "status": "success", "billed": true, "cached": false, "html_url": "https://api.proxyfield.io/v1/requests/req_7f3c9a1e52d84b0c/html", "tag": null},
  "ai_overview": {"status": "present", "markdown": "An espresso machine forces hot water through finely ground coffee at about 9 bar of pressure [1][2]. ...", "citations": [{"position": 1, "title": "Espresso machine", "url": "https://en.wikipedia.org/wiki/Espresso_machine", "domain": "en.wikipedia.org", "snippet": "An espresso machine brews coffee by forcing pressurized water near boiling point through a puck of ground coffee."}]},
  "organic_results": [{"position": 1, "title": "Espresso machine - Wikipedia", "url": "https://en.wikipedia.org/wiki/Espresso_machine", "displayed_url": "en.wikipedia.org › wiki › Espresso_machine", "domain": "en.wikipedia.org", "snippet": "An espresso machine brews coffee by forcing pressurized water near boiling point through a puck of ground coffee and a filter.", "date": null, "sitelinks": []}],
  "related_questions": [{"position": 1, "question": "What is the difference between espresso and coffee machines?", "answer": "Espresso machines use pressure to push water through finely ground coffee, while drip machines let water flow through coarser grounds by gravity.", "source": {"title": "Espresso vs drip coffee", "url": "https://www.example-coffee-guide.com/espresso-vs-drip", "domain": "www.example-coffee-guide.com"}}],
  "pagination": {"current_page": 1, "next_page": 2}
}

The example is shortened; a full response has every block of the table, null or [] where the page has none.

One request is one prompt and returns one answer.

The response holds answer_text, answer_markdown (with [n] source markers), text_blocks[] (paragraphs, lists and tables) and citations[]. If Google shows no AI Mode answer, metadata.status is no_result, the answer fields are null and nothing is billed. Follow-up questions in the same conversation are not part of the first version. The AI Overview inside a normal results page comes from the Google SERP API.

Each prompt is asked in a fresh conversation and returns that one answer.

# The request the ChatGPT scraper API takes (access through Contact sales)
curl https://api.proxyfield.io/v1/chatgpt \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What are good lightweight trail running shoes for beginners?", "country": "us", "web_search": true}'

{
  "metadata": {"id": "req_c40e8b2a9f1d6377", "api": "chatgpt", "status": "success", "billed": true, "cached": false, "tag": "brand-monitor-us"},
  "model": null,
  "web_search_used": true,
  "answer_markdown": "For beginners, look for a trail shoe with a **moderate drop**, a protective but flexible sole and **lugs of about 4 to 5 mm** [1]. ...",
  "citations": [{"position": 1, "title": "Trail running shoes: a beginner's guide", "url": "https://www.example-running.com/trail-shoes-beginners", "domain": "www.example-running.com", "snippet": "Lug depth and drop matter more than brand."}],
  "search_queries": [],
  "products": []
}

AI answers can take longer than a page fetch, so large runs go best as jobs (see Jobs and batches).

The response holds answer_text, answer_markdown (with [n] markers that point to the numbered sources), answer_html, model (or null), citations[] and related_questions[], the follow-ups Perplexity suggests. Each prompt returns that one answer and no data from any account.

Any public URL, fetched over plain HTTP or loaded in a browser. render alone decides the price: false is the HTTP price, true the JavaScript-rendering price.

output: html, markdown or text returns the body itself, with the site's status code in X-Target-Status and the URL after redirects in X-Final-Url. output: json returns metadata, parameters, status_code, final_url, content_type, headers (the site's), cookies[], content, screenshot (base64 or null) and actions_log[]. Blocked pages are retried on new IPs within timeout, and the retries are not billed. If no valid page comes back in time, the answer is 502 target_unavailable with the site's last status, not billed.

# The request the Web Scraping API takes (access through Contact sales)
curl https://api.proxyfield.io/v1/scrape \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.example-shop.com/category/grinders?page=2", "render": true, "wait_for": ".product-card", "country": "gb", "output": "json", "actions": [{"type": "click", "selector": "#accept-cookies"}, {"type": "scroll", "to": "bottom"}]}'

{
  "metadata": {"id": "req_41ac7e93d05f2b68", "api": "web_scrape", "status": "success", "billed": true, "cached": false, "html_url": null, "tag": null},
  "status_code": 200,
  "final_url": "https://www.example-shop.com/category/grinders?page=2",
  "content_type": "text/html; charset=utf-8",
  "cookies": [{"name": "consent", "value": "accepted", "domain": ".example-shop.com", "path": "/"}],
  "content": "<!DOCTYPE html><html lang=\"en-GB\"><head><title>Grinders - page 2</title></head><body>...</body></html>",
  "screenshot": null,
  "actions_log": [{"type": "click", "ok": true}, {"type": "scroll", "ok": true}]
}

Two operations: one product page, or one search or category results page.

The first version covers amazon.com, amazon.co.uk, amazon.de, amazon.fr, amazon.it, amazon.es, amazon.ca and amazon.co.jp; another marketplace returns 400 unsupported_marketplace. The zip_code is Amazon's own delivery setting on amazon.com, not a way to pick the IP.

• Product: asin, parent_asin, url, title, brand, price, price_strikethrough, currency, discount_percentage, coupon, stock, is_prime, delivery[], delivery_location, buybox (seller_name, seller_id, fulfilled_by_amazon), other_sellers_count, rating, reviews_count, sales_rank[], categories[], bullet_points[], description, images[], variations[], product_details.
• Search: results[] with position, organic_position, sponsored_position, is_sponsored, asin, title, url, image, price, price_strikethrough, currency, rating, reviews_count, sales_volume, is_prime, is_amazons_choice, is_best_seller; plus page, last_page and total_results. A results page with no products is still a result.
• An ASIN or URL with no product page returns 404 target_not_found, not billed. Review pages, the offers list and best-seller lists are not part of the first version.

# The request the Amazon scraper API takes (access through Contact sales)
curl https://api.proxyfield.io/v1/amazon/product \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"asin": "B0EXAMPLE7", "domain": "com", "zip_code": "10001"}'

One request returns one results page of up to 20 places.

Each place in places[] has position (counted across pages), title, place_id, address, phone, website, domain, rating, reviews_count, price_level, category, categories[], gps_coordinates, open_state, hours (per weekday), service_options, thumbnail and description; pagination gives current_page, next_page and places_on_page. Review texts, emails and single-place details are not part of the first version.

{
  "metadata": {"id": "req_5d2e7a9c0b4f8136", "api": "google_maps", "status": "success", "billed": true, "cached": false, "tag": null},
  "parameters": {"q": "coffee roasters", "ll": "@30.2672,-97.7431,14z", "location": null, "gl": "us", "hl": "en", "page": 1},
  "places": [{"position": 1, "title": "Example Roasting Co.", "place_id": "ChIJexample0101AustinTX", "address": "507 Example Ave, Austin, TX 78702", "phone": "+1 512-555-0187", "website": "https://www.example-roasting.com/", "domain": "www.example-roasting.com", "rating": 4.8, "reviews_count": 1126, "category": "Coffee roasters"}]
}

Every API can also run as a job: a job takes the same parameters as the direct call and returns the same body in result. Use jobs for AI answers and for large runs.

• A job has up to 10 minutes; its timeout is ignored.
• Results are kept for 48 hours after the job finishes (expires_at), then return 410 expired. Fetching a result again is not billed.
• callback_url receives a POST of the finished job, result included, signed with X-ProxyField-Signature: sha256=<HMAC of the body with your webhook secret>. A failed callback is retried 3 times. A batch calls it once per job.

{
  "id": "bat_7e19c4a2d0f5b683",
  "api": "google_search",
  "counts": {"total": 2, "queued": 2, "running": 0, "done": 0, "failed": 0},
  "jobs": [{"index": 0, "id": "job_a1b2c3d4e5f60718", "status": "queued"}, {"index": 1, "id": "job_a1b2c3d4e5f60719", "status": "queued"}]
}

Helpers, none of them billed: GET /v1/google/locations, GET /v1/jobs/{id}, GET /v1/batches/{id}, GET /v1/requests/{id}/html and GET /v1/usage, which counts billed results and unbilled requests per API and day.

The scraper APIs are billed on successful results only, priced per 1,000 successful results (prices in the table above and on pricing).

Billed (X-Billed: true, metadata.billed: true):

• a response with metadata.status: success;
• Web Scraping API: a site's 2xx answer, including a sign-in page the site serves with a 200 status, and a site's 404 or 410;
• a job that ends done with a result, by the same rule as a direct call.

Not billed:

• every error response (4xx, 5xx): bad parameters, an empty balance, rate limits, our failures, target_unavailable, timeout;
• AI APIs: no_result, when the engine showed no answer;
• Amazon: 404 target_not_found;
• our internal retries: only the final delivered result counts;
• jobs that end failed;
• cached results: on Google search and Maps, the same parameters within 1 hour come from the cache with metadata.cached: true and X-Cache: hit; no_cache: true fetches fresh and is billed;
• the helpers.

Volume price: the lower price of each API applies from 10,000 successful results in one purchase.

Payment: the APIs are paid from the same crypto balance as ProxyField proxies, in USDT, BTC, ETH or 10 other coins (crypto payments). The balance never expires, and there is no subscription or monthly fee.

• 20 requests at once per account (direct calls in flight); the next one returns 429 concurrency_limit with Retry-After. Higher limits through sales. Your account's own limit is in X-Concurrency-Limit and in GET /v1/usage.
• Up to 1,000 requests in one batch; a larger batch returns 400 invalid_parameter.
• Too many calls in a short time return 429 rate_limited with Retry-After.
• Limits apply per account, never per key, and a 429 is never billed.

Errors use real HTTP status codes and one body: error with code, message, param and target_status, plus request_id.

{
  "error": {"code": "unsupported_combination", "message": "wait_for needs render=true.", "param": "wait_for", "target_status": null},
  "request_id": "req_b7d40e2c19a6f853"
}

• Expanded People Also Ask, which ProxyField does not sell.
• Other Google tabs and engines (News, Images, the Shopping tab, Jobs, Bing), and parsed endpoints for other sites: the Web Scraping API fetches those pages as HTML, Markdown or text.
• Postal-code locations for Google, and Amazon delivery ZIP codes outside amazon.com.
• Amazon review pages, the offers list and best-seller lists; Google Maps review texts and single-place details.
• Follow-up turns in AI Mode and ChatGPT: one request is one answer.
• GET requests and a key in the query string.
• SDKs, an MCP server, and a no-code dashboard with CSV export.

Acceptable use applies to every request: public pages only, and follow the site's terms (acceptable use policy).