proxies & location

every request we make to a target site goes out through a proxy. both /api/scrape and /api/map accept the same proxy and location parameters: proxy controls which tier is used — and with it, the cost multiplier and retrieval success rate — while location controls where the request appears to originate.

proxy tiers

tier	multiplier	description
`basic`	×1	fast, and usually works — good for most public sites.
`advanced`	×5	enhanced proxy tier with a higher success rate.
`auto`	×1 or ×5	we pick the tier and bill whichever one delivers the result.

see credits & pricing for the full cost breakdown, including map requests and add-ons.

default is "auto". when you omit proxy, the request reserves its engine’s advanced-proxy ceiling and bills at the tier that actually delivered the result. http is 1 or 5 credits; browser is 3 or 15; screenshot is 5 or 25. set the tier explicitly in the request body to pin it:


{
  "url": "https://example.com",
  "proxy": "advanced"
}

when to use each tier

basic — start here. fast, and usually works: blogs, news, documentation, public pages, SPAs.
advanced — uses an enhanced proxy pool for a higher success rate when reliability matters more than the lowest cost.
auto — best for general-purpose scrapers where you don’t know the target sites in advance. you pay basic rates when basic works, and only pay advanced rates when necessary.

advanced costs 5x more than basic. don’t use it as a default. start with basic or auto, and only pin to advanced for specific domains you know need it.

how `auto` works

the auto tier optimizes for success at the lowest cost:

the request is first attempted with the basic tier (×1).
if the basic attempt fails to deliver, the request is retried with the advanced tier (×5).
you’re billed for whichever tier actually delivered the result.

in other words, you get the higher success rate of advanced when it is needed, but pay basic rates whenever basic is enough.

if basic succeeds, the engine base is unchanged. if only advanced succeeds, the engine base is multiplied by 5. if both fail, the reservation is released and you pay nothing.

the tier that actually served (and was billed for) the request is reported back on the response as response_meta.usage.proxy — it’s always the resolved tier, basic or advanced, never auto. see credits & pricing for the full response_meta.usage shape.

reservations are per endpoint. an auto scrape needs at least 15 available credits without a screenshot, or 25 with one, even if the delivered result costs less; requesting screenshot slicing adds 1 to the reservation. /api/map reserves at the http base — 1 on basic, 5 on auto or advanced. see how billing works for why.

proxy and cache interaction

cached results are proxy-agnostic. a result cached from a basic request will serve an advanced request for the same url, and vice versa. the proxy tier only matters when the cache is missed and a fresh scrape is needed.

this means switching proxy tiers doesn’t invalidate your cache — a fully cached result stays free regardless of the proxy setting. a newly produced screenshot-slice variant costs +1.

location emulation

use the location object to make a request as if visiting from a specific locale or country:


{
  "url": "https://example.com",
  "proxy": "basic",
  "location": {
    "locale": "de-DE",
    "country": "DE"
  }
}

locale (bcp-47, e.g. en-US, de-DE) — sets the Accept-Language header and navigator.language.
country — selects the proxy exit country. accepts an iso 3166-1 alpha-2 code (e.g. US, DE) or one of the regional values below.

useful for geo-targeted pricing pages, localized content, and region-specific availability checks.

/api/map accepts location.country for proxy egress, but not location.locale — sitemaps and link discovery don’t vary by Accept-Language. On /api/scrape, both fields apply.

regional country values

besides a specific country code, country accepts two regional values that route through a randomly-chosen country from the matching pool. country codes and regional values are case-insensitive, so eu, EU, and Eu are equivalent, as are europe, Europe, and EUROPE.

value	routes from
`eu`	a random eu member state.
`europe`	a random European country — the eu members plus other European states, including the uk.


{
  "url": "https://example.com",
  "proxy": "basic",
  "location": {
    "country": "eu"
  }
}

eu and europe are not aliases: eu stays within the European Union, while europe draws from a wider set of European countries (the eu members plus non-eu states such as the uk, Switzerland, and Norway). use eu when you specifically need an eu-jurisdiction exit; use europe when any European exit will do.

Both regional values work on /api/scrape and /api/map wherever country is accepted.