> ## Documentation Index
> Fetch the complete documentation index at: https://usefoil.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent IP rotation API

> Check whether an agent should rotate its current proxy IP address.

Use the Agent IP rotation API before assigning proxy IPs to agents. Submit between one and ten public IPv4 or IPv6 addresses to receive ordered rotation recommendations based on Foil's IP intelligence.

> [!WARNING]
>
> Ask Foil to enable this endpoint for your organization, then authenticate with a secret key that has the `agents:ip_rotation` scope. Call it only from your server. Never expose the secret key to an agent page.

If Foil hasn't enabled the endpoint for your organization, the API returns `404` with `request.not_found`, the same response as for an unknown route. Foil checks this before it checks the key's scopes. If the endpoint is enabled but the key lacks the scope, the API returns `403` with `auth.insufficient_scope`.

## `POST /v1/agents/ip-rotation`

```bash theme={"dark"}
curl https://api.usefoil.com/v1/agents/ip-rotation \
  -X POST \
  -H "Authorization: Bearer $FOIL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "ip": "8.8.8.8",
        "proxy_provider": "BYTEFUL",
        "desired_country_code": "US"
      }
    ]
  }'
```

Each item requires the agent's current public IP, a provider tag from Foil's operator catalog, and an uppercase ISO 3166-1 alpha-2 desired country code. Foil matches the tag exactly and accepts catalogued aliases, so `BYTEFUL_ISP`, `BYTEFUL_DATA`, and the legacy `PINGPROXIES` tags all resolve to `BYTEFUL`. Foil never infers a suffix from a shared stem. Responses preserve request order.

> [accordion] Accepted provider tags
>
> Send the tag in the first column as `proxy_provider`. Tags in the last column are catalogued aliases and resolve to the same operator; the response reports the canonical tag in `proxy_provider_brand`.
>
> | Tag | Operator | Category | Also accepted |
> | - | - | - | - |
> | `2CAPTCHA` | 2Captcha | Residential proxy | |
> | `711PROXY` | 711Proxy | Residential proxy | |
> | `9PROXY` | 9Proxy | Residential proxy | |
> | `ADGUARDVPN` | AdGuard VPN | Consumer VPN | |
> | `AHREFS` | Ahrefs | Crawler / agent | |
> | `AMAZON` | Amazon | Crawler / agent | `AMAZON_BOT`, `AMAZON_SEARCHBOT`, `AMAZON_USER` |
> | `ANGELVPN` | AngelVPN | Consumer VPN | |
> | `ANTHROPIC` | Anthropic | Crawler / agent | |
> | `ANYIP` | AnyIP | Residential proxy | `ANYIP_MOBILE`, `ANYIP_PROXY` |
> | `APIFY` | Apify | Crawler / agent | |
> | `APPVPNTRION` | App VPN (Trion AI Studio) | Consumer VPN | |
> | `ARACHNET` | Arachnet | Residential proxy | |
> | `ASHOVPN` | Asho VPN | Consumer VPN | |
> | `ASTROPROXY` | Astro | Residential proxy | |
> | `AZADITUNNEL` | AzadiTunnel | Consumer VPN | |
> | `B2PROXY` | B2Proxy | Proxy network | |
> | `BARTPROXIES` | Bart Proxies | Residential proxy | `BARTPROXIES_ISP`, `BARTPROXIES_RESI` |
> | `BIGMAMA` | BigMama | Residential proxy | `BIGMAMA_PROXY` |
> | `BINARYEDGE` | BinaryEdge | Crawler / agent | |
> | `BING` | Microsoft Bing | Crawler / agent | |
> | `BIRDPROXIES` | BirdProxies | Residential proxy | `BIRDPROXIES_GLOBAL_CONTROL`, `BIRDPROXIES_IN`, `BIRDPROXIES_PERFORMANCE`, `BIRDPROXIES_PH`, `BIRDPROXIES_PK` |
> | `BITDEFENDERVPN` | Bitdefender VPN | Consumer VPN | |
> | `BLURPATH` | BlurPath | Residential proxy | |
> | `BOTTINGTOOLS` | BottingTools | Residential proxy | `BOTTINGTOOLS_BASIC`, `BOTTINGTOOLS_ISP`, `BOTTINGTOOLS_PREMIUM` |
> | `BRAVEVPN` | Brave VPN | Consumer VPN | `BRAVE_VPN` |
> | `BRIGHTDATA` | Bright Data | Proxy network | `BRIGHTDATA_DATACENTER`, `LUMINATI_PROXY` |
> | `BROWSERBASE` | Browserbase | Crawler / agent | |
> | `BROWSERUSE` | Browser Use | Crawler / agent | `BROWSER_USE` |
> | `BYTEFUL` | Byteful | Residential proxy | `BYTEFUL_DATA`, `BYTEFUL_ISP`, `PINGPROXIES`, `PINGPROXIES_ISP`, `PINGPROXIES_MOBILE`, `PING_PROXIES` |
> | `CANDYVPN` | Candy VPN | Consumer VPN | |
> | `CATONETWORKS` | Cato Networks | Enterprise egress | |
> | `CISCOUMBRELLA` | Cisco Umbrella | Enterprise egress | `CISCO_SECURE_WEB_GATEWAY` |
> | `CLIPROXY` | Cliproxy | Residential proxy | |
> | `COPROXY` | CoProxy | Residential proxy | |
> | `COREPROXY` | CoreProxy | Residential proxy | |
> | `CYBERGHOST` | CyberGhost | Consumer VPN | `CYBERGHOSTPROXY` |
> | `DATABAY` | Databay | Proxy network | `DATABAY_MOBILE` |
> | `DATADOG` | Datadog | Crawler / agent | |
> | `DATAIMPULSE` | DataImpulse | Residential proxy | `DATAIMPULSE_DATACENTER`, `DATAIMPULSE_MOBILE`, `DATAIMPULSE_PREMIUM`, `DATAIMPULSE_PROXY` |
> | `DATARAMA` | Datarama | Residential proxy | `DATARAMA_PREMIUM`, `DATARAMA_UNIVERSAL` |
> | `DECODO` | Decodo | Residential proxy | `DECODO_BD`, `DECODO_COUNTRY_GB`, `DECODO_DATACENTER`, `DECODO_GB`, `DECODO_GLOBAL_CONTROL`, `DECODO_ID`, `DECODO_ISP` |
> | `DEEPERNETWORK` | Deeper Network | Consumer VPN | `DEEPERVPN` |
> | `DEFYXVPN` | Defyx VPN | Consumer VPN | |
> | `DETECTEXPERT` | Detect.Expert | Residential proxy | |
> | `DOTCOMMONITOR` | Dotcom-Monitor | Crawler / agent | |
> | `DRIVERDEV` | Driver.dev | Crawler / agent | `DRIVERDEV_DATACENTER`, `DRIVERDEV_ISP` |
> | `DUCKDUCKGO` | DuckDuckGo | Consumer VPN | `DUCKDUCKGO_ASSIST`, `DUCKDUCKGO_SEARCH` |
> | `EARNFM` | EarnFM | Residential proxy | `EARNFM_PROXY` |
> | `ELUSIVE` | Elusive Proxy | Residential proxy | `ELUSIVE_PROXY` |
> | `ELUSIVESH` | Elusive.sh | Residential proxy | |
> | `ENIGMAPROXY` | EnigmaProxy | Residential proxy | `ENIGMAPROXY_BUDGET` |
> | `EPROXIES` | EProxies | Residential proxy | |
> | `EVOMI` | Evomi | Residential proxy | `EVOMI_CORE`, `EVOMI_DATACENTER`, `EVOMI_ISP`, `EVOMI_MOBILE` |
> | `EXPRESSVPN` | ExpressVPN | Consumer VPN | |
> | `EZPROXIES` | EZProxies | Residential proxy | `EZPROXIES_ISP` |
> | `FASTVPN` | FastVPN | Consumer VPN | |
> | `FIRECRAWL` | Firecrawl | Crawler / agent | `FIRECRAWL_DATACENTER`, `FIRECRAWL_ISP` |
> | `FIREFOXVPN` | Firefox VPN | Consumer VPN | |
> | `FLAMEPROXIES` | Flame Proxies | Residential proxy | |
> | `FLASHPROXY` | FlashProxy | Residential proxy | `FLASHPROXIES_ISP`, `FLASHPROXY_DATACENTER`, `FLASHPROXY_ISP`, `FLASHPROXY_LITE`, `FLASHPROXY_MOBILE` |
> | `FLEETPROXY` | FleetProxy | Residential proxy | |
> | `FLEXYPROXIES` | Flexyproxies | Residential proxy | |
> | `FLOPPYDATA` | Floppydata | Residential proxy | |
> | `FORCEPOINTONESSE` | Forcepoint ONE | Enterprise egress | |
> | `FORTISASE` | Fortinet FortiSASE | Enterprise egress | |
> | `FREEANDROIDVPN` | Free Android VPN | Consumer VPN | |
> | `GEEKPROXY` | GeekProxy | Residential proxy | `GEEKPROXY_FLEX`, `GEEKPROXY_TURBO` |
> | `GEONIX` | Geonix | Proxy network | `GEONIX_ISP` |
> | `GEONODE` | Geonode | Residential proxy | `GEONODE_DATACENTER`, `GEONODE_PROXY` |
> | `GETGRASS` | Grass | Residential proxy | |
> | `GLORYCLOUD` | GloryCloud (GoProxy) | Proxy network | |
> | `GOOGLE` | Google | Crawler / agent | `GOOGLE_ADBOT`, `GOOGLE_AGENT`, `GOOGLE_CRAWLER`, `GOOGLE_FETCHER`, `GOOGLE_VERIFIER` |
> | `GOOGLEVPN` | Google VPN | Consumer VPN | `GOOGLE_FI_VPN`, `GOOGLE_ONE_VPN` |
> | `GOPROXIES` | GoProxies | Residential proxy | |
> | `GUARDIAN` | Guardian Firewall + VPN | Consumer VPN | `GUARDIANFIREWALLVPN` |
> | `HAKUNAVPN` | HakunaVPN | Consumer VPN | |
> | `HELLWORLD` | Hell World | Residential proxy | `HELLWORLD_FPRIVATE`, `HELLWORLD_GOATX` |
> | `HETRIXTOOLS` | HetrixTools | Crawler / agent | |
> | `HIDEMYASS` | HideMyAss | Consumer VPN | `HMA` |
> | `HOLAVPN` | Hola VPN | Consumer VPN | |
> | `HOTSPOTSHIELD` | Hotspot Shield | Consumer VPN | |
> | `HPROXY` | HProxy | Residential proxy | `HPROXY_LITE`, `HPROXY_PREMIUM` |
> | `HUBVPN` | Hub VPN | Consumer VPN | `HUBVPNPRO` |
> | `HYDRAPROXY` | HydraProxy | Residential proxy | |
> | `HYPEPROXIES` | HypeProxies | Proxy network | `HYPEPROXIESISP`, `HYPEPROXIES_DATACENTER`, `HYPEPROXIES_ISP` |
> | `IBOSS` | iboss | Enterprise egress | |
> | `ICEYPROXIES` | Icey Proxies | Residential proxy | `ICEYPROXIES_BASIC`, `ICEYPROXIES_ELITE`, `ICEYPROXIES_PREMIUM`, `ICEYPROXIES_PRIVATE`, `ICEYPROXIES_PRIVATE2` |
> | `ICLOUD` | iCloud Private Relay | Consumer VPN | `AKAMAI_QUILL`, `APPLE`, `APPLE_PRIVATE_RELAY` |
> | `INFATICA` | Infatica | Residential proxy | `INFATICA_APOLLO`, `INFATICA_ATHENA`, `INFATICA_DATACENTER`, `INFATICA_DATACENTER1`, `INFATICA_DATACENTER2`, `INFATICA_DATACENTER_POOL2`, `INFATICA_HERA`, `INFATICA_HERMES`, `INFATICA_ISP`, `INFATICA_POOL1`, `INFATICA_POOL10`, `INFATICA_POOL2`, `INFATICA_POOL3`, `INFATICA_POOL4`, `INFATICA_POOL5`, `INFATICA_POOL6`, `INFATICA_POOL7`, `INFATICA_POOL8`, `INFATICA_POOL9`, `INFATICA_PREMIUM`, `INFATICA_PROXY`, `INFATICA_ZEUS` |
> | `INFINITEPROXIES` | InfiniteProxies | Residential proxy | |
> | `INSIDEPROXY` | InsideProxy | Proxy network | `INSIDEPROXY_LITE`, `INSIDEPROXY_POOL2`, `INSIDEPROXY_POOL4` |
> | `IP2UP` | IP2UP | Residential proxy | |
> | `IPCOLA` | IPCola | Proxy network | `IPCOLA_DATACENTER`, `IPCOLA_PROXY` |
> | `IPCOOK` | IPCook | Proxy network | |
> | `IPFOXY` | IPFoxy | Residential proxy | |
> | `IPIDEA` | IPIDEA | Residential proxy | `IPIDEA_ADAM`, `IPIDEA_ATOM`, `IPIDEA_BURST`, `IPIDEA_CAIN`, `IPIDEA_CANDY`, `IPIDEA_CHEEK`, `IPIDEA_CIS`, `IPIDEA_CUSTOM`, `IPIDEA_DAO`, `IPIDEA_DATACENTER`, `IPIDEA_DIO`, `IPIDEA_FECA`, `IPIDEA_GEOMIX`, `IPIDEA_HOSTING`, `IPIDEA_IPWEB`, `IPIDEA_ISP`, `IPIDEA_KKOIP`, `IPIDEA_LOTUS`, `IPIDEA_MISTY`, `IPIDEA_MIX`, `IPIDEA_MIX2`, `IPIDEA_MIX3`, `IPIDEA_MIX4`, `IPIDEA_MIXAS`, `IPIDEA_MOB`, `IPIDEA_OCPUTOS`, `IPIDEA_OGS`, `IPIDEA_OXY`, `IPIDEA_OXY1`, `IPIDEA_OXY2`, `IPIDEA_PDK`, `IPIDEA_POOL`, `IPIDEA_PROXY`, `IPIDEA_PY`, `IPIDEA_QUARK`, `IPIDEA_RESI`, `IPIDEA_SDKPROXY`, `IPIDEA_SECRET`, `IPIDEA_SPARK1`, `IPIDEA_STARS`, `IPIDEA_STATIC`, `IPIDEA_STO262037`, `IPIDEA_STO322539`, `IPIDEA_STO354892`, `IPIDEA_STO521149`, `IPIDEA_TEST`, `IPIDEA_TOM`, `IPIDEA_WIND`, `IPIDEA_ZO`, `IPIDEA_ZONE` |
> | `IPLOOP` | IPLoop | Residential proxy | |
> | `IPPEAK` | IPPeak | Residential proxy | `IPPEAK_ISP` |
> | `IPROCKET` | IPRocket | Proxy network | `IPROCKET_PREMIUM` |
> | `IPROXYSHOP` | iProxy.shop | Residential proxy | `IPROXYSHOP_PROXY` |
> | `IPROYAL` | IPRoyal | Proxy network | `IPROYAL_DATACENTER`, `IPROYAL_ISP`, `IPROYAL_PROXY` |
> | `IPSHARKK` | IpSharkk | Residential proxy | `IPSHARKK_PROXY` |
> | `IPSTERR` | IPsterr | Residential proxy | `IPSTERR_MOBILE` |
> | `IPVANISH` | IPVanish | Consumer VPN | |
> | `IPWEB` | IPWeb | Proxy network | `IPWEB_ISP` |
> | `IVACY` | Ivacy | Consumer VPN | |
> | `JAGUAR` | Jaguar | Residential proxy | |
> | `JNTUNNEL` | JN Tunnel | Consumer VPN | |
> | `JUICEVPN` | Juice VPN | Consumer VPN | |
> | `KKOIP` | KKOIP | Residential proxy | |
> | `KOCERROXY` | KocerRoxy | Residential proxy | |
> | `KOOKEEY` | Kookeey | Proxy network | `KOOKEEY_PROXY` |
> | `LEMONLABS` | Lemon Labs (LemonClub) | Residential proxy | `LEMONCLUB_ISP`, `LEMONLABS_LEMONNUT`, `LEMONLABS_MOBILE` |
> | `LIGHTNINGPROXIES` | LightningProxies | Residential proxy | `LIGHTINGPROXIES_MOBILE`, `LIGHTNINGPROXIES_ISP`, `LIGHTNINGPROXIES_PREMIUM` |
> | `LINKFOG` | Linkfog | Residential proxy | |
> | `LITPORT` | Litport | Residential proxy | `LITPORT_MOBILE`, `LITPORT_NET` |
> | `LUXPROXY` | LuxProxy | Residential proxy | |
> | `MAGNETICPROXY` | MagneticProxy | Residential proxy | `MAGNETICPROXY_AI`, `MAGNETICPROXY_PREMIUM`, `MAGNETICPROXY_STANDARD` |
> | `MASKIFY` | Maskify | Residential proxy | |
> | `MASSIVE` | Massive | Proxy network | `MASSIVE_ISP`, `MASSIVE_PROXY` |
> | `MECOOL` | Mecool | Residential proxy | |
> | `MELLOWTEL` | Mellowtel | Proxy network | `MELLOWTEL_PROXY` |
> | `MENLOSECURITY` | Menlo Security | Enterprise egress | |
> | `MISTRAL` | Mistral AI | Crawler / agent | `MISTRAL_INDEX`, `MISTRAL_USER` |
> | `MOMOPROXY` | MoMoProxy | Residential proxy | |
> | `MOUNTPROXY` | Mount Proxy | Residential proxy | `MOUNT_PROXY` |
> | `MULLVAD` | Mullvad | Consumer VPN | |
> | `MYSTERIUM` | Mysterium Network | Proxy network | |
> | `MYXPROXY` | myx | Residential proxy | `MYXPROXY_LITE`, `MYXPROXY_MOBILE` |
> | `NET2FAST` | Net2Fast | Residential proxy | |
> | `NETNUT` | NetNut | Proxy network | `NETNUT_PROXY` |
> | `NETSKOPE` | Netskope | Enterprise egress | |
> | `NETTIFY` | Nettify | Residential proxy | `NETTIFY_BUDGET`, `NETTIFY_DATACENTER`, `NETTIFY_GLOBAL_CONTROL`, `NETTIFY_IN`, `NETTIFY_MOBILE`, `NETTIFY_PK` |
> | `NETVORTEX` | NetVortex | Residential proxy | `NETVORTEX_GLOBAL_CONTROL`, `NETVORTEX_IN`, `NETVORTEX_PK`, `NETVORTEX_TH` |
> | `NEWIPNOW` | NewIPNow | Proxy network | `NEWIPNOW_DATACENTER` |
> | `NEWRELIC` | New Relic | Crawler / agent | |
> | `NEXTPROXY` | NextProxy | Proxy network | `NEXTPROXY_ISP` |
> | `NIMBLE` | Nimble | Residential proxy | `NIMBLEWAY_PROXY` |
> | `NIUPROXY` | NiuProxy | Residential proxy | `NIUPROXY_PRO` |
> | `NODEMAVEN` | NodeMaven | Proxy network | `NODEMAVEN_BD`, `NODEMAVEN_DATACENTER`, `NODEMAVEN_GLOBAL_CONTROL`, `NODEMAVEN_IN`, `NODEMAVEN_ISP`, `NODEMAVEN_MOBILE`, `NODEMAVEN_PK`, `NODEMAVEN_PROXY` |
> | `NORDLAYER` | NordLayer | Enterprise egress | |
> | `NORDVPN` | NordVPN | Consumer VPN | |
> | `NOVADA` | Novada | Proxy network | `NOVADA_ISP` |
> | `NOVAPROXY` | NovaProxy | Residential proxy | `NOVAPROXY_BUDGET`, `NOVAPROXY_PREMIUM` |
> | `NOVPROXY` | Novproxy | Residential proxy | |
> | `NSOCKS` | Nsocks | Residential proxy | `NSOCKS_PROXY` |
> | `NSTDATA` | NST Data | Residential proxy | `NSTDATA_LITE`, `NSTPROXY` |
> | `NULLVAULT` | NullVault | Residential proxy | |
> | `OCTOHIDE` | Octohide VPN | Consumer VPN | |
> | `OCULUSPROXIES` | Oculus Proxies | Residential proxy | `OCULUSPROXIES_DATACENTER`, `OCULUSPROXIES_ISP`, `OCULUSPROXIES_SNEAKER`, `OCULUSPROXIES_TICKET` |
> | `OKKPROXY` | OkkProxy | Residential proxy | `OKKPROXY_MINI`, `OKKPROXY_MOBILE`, `OKKPROXY_PRO`, `OKKPROXY_PROMAX` |
> | `OPENAI` | OpenAI | Crawler / agent | `OPENAI_ADSBOT`, `OPENAI_GPTBOT`, `OPENAI_SEARCHBOT`, `OPENAI_USER` |
> | `ORBITVPN` | Orbit VPN | Consumer VPN | |
> | `OUTLINE` | Outline VPN | Consumer VPN | `OUTLINEKEYS`, `OUTLINEVPN` |
> | `OXYLABS` | Oxylabs | Residential proxy | `OXYLABS_DATACENTER`, `OXYLABS_GB`, `OXYLABS_ISP`, `OXYLABS_PROXY` |
> | `PACKETSTREAM` | PacketStream | Residential proxy | `PACKETSTREAM_PROXY` |
> | `PALOALTO_XPANSE` | Palo Alto Xpanse | Enterprise egress | |
> | `PERIMETER81` | Perimeter 81 (Check Point) | Enterprise egress | |
> | `PERPLEXITY` | Perplexity | Crawler / agent | `PERPLEXITY_BOT`, `PERPLEXITY_USER` |
> | `PIA` | Private Internet Access | Consumer VPN | `PRIVATE_INTERNET_ACCESS` |
> | `PIPROXIES` | PI Proxies | Residential proxy | `PIPROXIES_PREMIUM` |
> | `PLAINPROXIES` | PlainProxies | Proxy network | `PLAINPROXIES_DATACENTER`, `PLAINPROXIES_ISP`, `PLAINPROXIES_PROXY` |
> | `PLANETVPN` | Planet VPN | Consumer VPN | `FREEVPNPLANET`, `FREE_VPN_PLANET` |
> | `POWERVPN` | Power VPN | Consumer VPN | `SECUREVPNPROXY` |
> | `PRIVADOVPN` | PrivadoVPN | Consumer VPN | |
> | `PRIVATEBYTE` | PrivateByte | Residential proxy | `PRIVATEBYTE_CLEAN`, `PRIVATEBYTE_STANDARD`, `PRIVATEBYTE_STICKYCLEAN` |
> | `PRIVATEPROXY` | PrivateProxy | Residential proxy | `PRIVATEPROXY_DATACENTER`, `PRIVATEPROXY_ISP` |
> | `PROSOX` | Prosox | Residential proxy | |
> | `PROTONVPN` | Proton VPN | Consumer VPN | |
> | `PROXIDIZE` | Proxidize | Residential proxy | `PROXIDIZE_MOBILE` |
> | `PROXIESFO` | Proxies.fo | Residential proxy | `PROXIES_FO` |
> | `PROXIWARE` | Proxiware | Proxy network | `PROXIWARE_ECO`, `PROXIWARE_PREMIUM` |
> | `PROXY4U` | Proxy4u | Residential proxy | |
> | `PROXYARAB` | Proxy Arab | Proxy network | |
> | `PROXYBASE` | Proxy Base | Residential proxy | |
> | `PROXYBR` | ProxyBR | Proxy network | |
> | `PROXYCC` | PROXY.CC | Residential proxy | `PROXY_CC` |
> | `PROXYCHEAP` | Proxy-Cheap | Residential proxy | `PROXY_CHEAP` |
> | `PROXYEMPIRE` | ProxyEmpire | Residential proxy | `PROXYEMPIRE_DATACENTER`, `PROXYEMPIRE_MOBILE` |
> | `PROXYGEN` | ProxyGen | Residential proxy | |
> | `PROXYON` | Proxyon | Residential proxy | |
> | `PROXYRACK` | ProxyRack | Residential proxy | `PROXYRACK_PROXY` |
> | `PROXYRISE` | ProxyRise | Proxy network | |
> | `PROXYSALE` | ProxySale | Residential proxy | `PROXYSALE_POOL1`, `PROXYSALE_POOL2` |
> | `PROXYSCRAPE` | ProxyScrape | Residential proxy | |
> | `PROXYSELLER` | Proxy-Seller | Residential proxy | `PROXYSELLER_DATACENTER`, `PROXYSELLER_ISP`, `PROXY_SELLER` |
> | `PROXYSHARD` | ProxyShard | Proxy network | `PROXYSHARD_PREMIUM` |
> | `PROXYSIO` | Proxys.io | Proxy network | `PROXYSIO_DATACENTER` |
> | `PROXYSTORE` | ProxyStore | Proxy network | `PROXYSTORE_ISP` |
> | `PROXYWING` | ProxyWing | Residential proxy | `PROXYWING_DATACENTER`, `PROXYWING_ISP`, `PROXYWING_PREMIUM`, `PROXYWING_STANDARD`, `PROXYWING_STANDARD_BD`, `PROXYWING_STANDARD_GLOBAL_CONTROL`, `PROXYWING_STANDARD_IN` |
> | `PSIPHON` | Psiphon | Consumer VPN | |
> | `PUREVPN` | PureVPN | Consumer VPN | `PUREVPNPROXY` |
> | `QUANTUMPROXIES` | Quantum Proxies | Proxy network | `QUANTUMPROXIES_ISP` |
> | `RAPIDSEEDBOX` | RapidSeedbox | Proxy network | `RAPIDSEEDBOX_DATACENTER`, `RAPIDSEEDBOX_ISP` |
> | `RARECLOUD` | RareCloud | Proxy network | `RARECLOUD_ISP` |
> | `RAYOBYTE` | Rayobyte | Residential proxy | `RAYOBYTE_DATACENTER`, `RAYOBYTE_ISP`, `RAYOBYTE_PROXY` |
> | `REMPROXY` | RemProxy | Residential proxy | |
> | `RESIFACTORY` | Resifactory | Proxy network | `RESIFACTORY_PREMIUM` |
> | `RESIGG` | Resi.GG | Residential proxy | `RESI_GG` |
> | `RESIPROX` | ResiProx | Residential proxy | |
> | `ROCKETVPNGO` | Rocket VPN Go | Consumer VPN | |
> | `ROLA` | Rola-IP | Residential proxy | `ROLAIP`, `ROLAIP_DATACENTER`, `ROLAIP_MOBILE` |
> | `RSOCKS` | RSOCKS | Residential proxy | |
> | `SCRAPEOPS` | ScrapeOps | Crawler / agent | `SCRAPEOPS_LEVEL1`, `SCRAPEOPS_LEVEL2` |
> | `SCRAPERAPI` | ScraperAPI | Crawler / agent | |
> | `SEEKPROXY` | SeekProxy | Proxy network | |
> | `SENTINEL` | Sentinel | Proxy network | |
> | `SHIFTER` | Shifter | Residential proxy | `SHIFTER_PROXY` |
> | `SKYHIGHWGCS` | Skyhigh Security | Enterprise egress | |
> | `SOAX` | SOAX | Residential proxy | `SOAX_MOBILE`, `SOAX_PROXY` |
> | `SPYDERPROXY` | SpyderProxy | Residential proxy | `SPYDERPROXY_BUDGET`, `SPYDERPROXY_PREMIUM` |
> | `SQUIDPROXIES` | SquidProxies | Proxy network | |
> | `STARRY` | Starry Proxy | Residential proxy | `STARRY_PROXY` |
> | `STATPROXIES` | Stat Proxies | Proxy network | `STATPROXIES_ISP` |
> | `STATUSCAKE` | StatusCake | Crawler / agent | |
> | `STRONGVPN` | StrongVPN | Consumer VPN | |
> | `SUPERVPNREALISTIC` | Super VPN (RealisticGame) | Consumer VPN | |
> | `SURFEASY` | SurfEasy | Consumer VPN | `SURF_EASY_VPN` |
> | `SURFSHARK` | Surfshark | Consumer VPN | |
> | `SWIFTPROXY` | Swiftproxy | Residential proxy | `SWIFTPROXY_NET` |
> | `SX` | SX.ORG | Residential proxy | `SX_ORG` |
> | `SYMANTEC` | Symantec (Broadcom) | Enterprise egress | |
> | `THORDATA` | Thordata | Residential proxy | |
> | `THUNDERPROXY` | Thunderproxy | Residential proxy | |
> | `TITANNET` | Titan Network | Proxy network | |
> | `TODYL` | Todyl | Enterprise egress | |
> | `TOR` | Tor Network | Anonymity network | `TOR_ENTRY`, `TOR_ENTRY_ISP`, `TOR_EXIT`, `TOR_EXIT_ISP`, `TOR_RELAY`, `TOR_RELAY_ISP` |
> | `TORCHPROXIES` | Torch Proxies | Residential proxy | `TORCHPROXIES_PREMIUM`, `TORCHPROXIES_X` |
> | `TORGUARD` | TorGuard | Consumer VPN | |
> | `TUNNELBEAR` | TunnelBear | Consumer VPN | |
> | `TURBOVPN` | Turbo VPN | Consumer VPN | `TURBOVPNLITE` |
> | `UDEALPROXY` | UDealProxy | Residential proxy | |
> | `ULTRASURF` | UltraSurf | Consumer VPN | `ULTRASURF_VPN` |
> | `URBANVPN` | Urban VPN | Consumer VPN | |
> | `V2CROSS` | V2Cross | Consumer VPN | `FOXOVPN`, `SHADOWROCKETANDROID` |
> | `V6PROXIES` | V6Proxies | Proxy network | `V6PROXIES_DATACENTER`, `V6PROXIES_ISP` |
> | `VANTAGE` | Vantage Proxies | Residential proxy | `VANTAGEPROXIES_APEX`, `VANTAGEPROXIES_CORE`, `VANTAGE_CORE` |
> | `VAULTPROXIES` | VaultProxies | Residential proxy | |
> | `VIBEPROXIES` | VibeProxies | Residential proxy | `VIBEPROXIES_PREMIUM` |
> | `VIRTUALSHIELD` | VirtualShield | Consumer VPN | |
> | `VITALPROXIES` | VitalProxies | Proxy network | `VITALPROXIES_BRIGHTDATA` |
> | `VMPARC` | VMP Arc | Consumer VPN | |
> | `VPNGATE` | VPN Gate | Consumer VPN | `OVPNPW` |
> | `VPNIFY` | vpnify | Consumer VPN | |
> | `VPNSUPER` | VPN Super | Consumer VPN | `MOBILEJUMPVPNIOS`, `VPNSUPERUNLIMITED`, `VPNSUPERUNLIMITEDIOS` |
> | `VYPRVPN` | VyprVPN | Consumer VPN | |
> | `WARP` | Cloudflare WARP | Consumer VPN | `CLOUDFLARE_WARP`, `CLOUDFLARE_ZERO_TRUST_NETWORK` |
> | `WEALTHPROXIES` | Wealth Proxies | Residential proxy | `WEALTHPROXIES_ISP` |
> | `WEBSHARE` | Webshare | Proxy network | `WEBSHARE_DATACENTER`, `WEBSHARE_ISP` |
> | `WINDSCRIBE` | Windscribe | Consumer VPN | |
> | `WIREDPROXIES` | WiredProxies | Proxy network | `WIREDPROXIES_DATACENTER`, `WIREDPROXIES_ISP` |
> | `WLVPN` | WLVPN | Consumer VPN | |
> | `XVPN` | X-VPN | Consumer VPN | |
> | `YILU` | YiLu Proxy | Residential proxy | `YILU_PROXY` |
> | `YUMIPROXY` | YumiProxy | Residential proxy | |
> | `ZENTRANET` | Zentranet | Residential proxy | |
> | `ZETTAPROXIES` | Zetta Proxies | Residential proxy | `ZETTAPROXIES_MOBILE` |
> | `ZIVPN` | ZIVPN | Consumer VPN | |
> | `ZSCALER` | Zscaler | Enterprise egress | |

```json theme={"dark"}
{
  "items": [
    {
      "ip": "8.8.8.8",
      "proxy_provider": "BYTEFUL",
      "desired_country_code": "US"
    }
  ]
}
```

The API echoes those values, adds the canonical brand key the tag resolved to, returns the observed country, confirms whether it matches, and tells you whether to cycle the IP:

```json theme={"dark"}
{
  "items": [
    {
      "ip": "8.8.8.8",
      "proxy_provider": "BYTEFUL",
      "proxy_provider_brand": "BYTEFUL",
      "desired_country_code": "US",
      "observed_country_code": "US",
      "country_matches": true,
      "should_cycle": false
    }
  ]
}
```

You can submit IPv4 or IPv6. If you submit a private, loopback, link-local, documentation, or otherwise non-global address, the API returns `422`.

`should_cycle` is `true` when Foil detects actionable proxy or anonymizer intelligence, when the IP sits on a hosting network (including static ISP-proxy ranges that carry the hosting trait), or when the observed country is confirmed to differ from the desired one. When the observed country cannot be confirmed, `observed_country_code` is `null` and `country_matches` is `false`, but that alone does not set `should_cycle`. Foil records the declared `proxy_provider` with the sighting and never lets it influence `should_cycle`; Foil does not check whether the IP belongs to that provider.

Foil validates the complete batch before performing any lookup. If any item is invalid, or the body contains a field other than `items`, the API returns `422` for the whole request. If the available intelligence cannot support a reliable negative decision for any item, the API returns `503` for the whole request instead of returning partial results. Retry according to the standard API error response.

The request costs one rate-limit unit for each submitted IP, so a batch of 10 costs 10 units. If IP rotation isn't enabled for your organization, the `404` costs one unit. See [Rate limits](https://usefoil.com/docs/api-reference/rate-limits.md#what-counts-against-the-limit).

Foil records every validated submitted IP, provider tag, and desired country code for the organization and API key that made the request. The batch is recorded atomically before intelligence lookup; if it cannot be recorded, the API returns `503` without performing the lookup.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.