> ## 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.
</Warning>

## `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 title="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` |
  | `ANTHROPIC` | Anthropic | Crawler / agent | |
  | `ANYIP` | AnyIP | Residential proxy | `ANYIP_MOBILE`, `ANYIP_PROXY` |
  | `APIFY` | Apify | Crawler / agent | |
  | `ARACHNET` | Arachnet | Residential proxy | |
  | `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_PERFORMANCE` |
  | `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` |
  | `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_DATACENTER`, `DECODO_ISP` |
  | `DEFYXVPN` | Defyx VPN | Consumer VPN | |
  | `DETECTEXPERT` | Detect.Expert | Residential proxy | |
  | `DOTCOMMONITOR` | Dotcom-Monitor | Crawler / agent | |
  | `DRIVERDEV` | Driver.dev | Crawler / agent | |
  | `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_ISP`, `EVOMI_MOBILE` |
  | `EXPRESSVPN` | ExpressVPN | Consumer VPN | |
  | `FASTVPN` | FastVPN | Consumer VPN | |
  | `FIRECRAWL` | Firecrawl | Crawler / agent | `FIRECRAWL_ISP` |
  | `FLAMEPROXIES` | Flame Proxies | Residential proxy | |
  | `FLASHPROXY` | FlashProxy | Residential proxy | `FLASHPROXIES_ISP`, `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 | |
  | `HELLWORLD` | Hell World | Residential proxy | `HELLWORLD_FPRIVATE`, `HELLWORLD_GOATX` |
  | `HETRIXTOOLS` | HetrixTools | Crawler / agent | |
  | `HIDEMYASS` | HideMyAss | Consumer VPN | `HMA` |
  | `HOLAVPN` | Hola VPN | 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` |
  | `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_DATACENTER`, `INFATICA_PREMIUM`, `INFATICA_PROXY` |
  | `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_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_ISP`, `IPROYAL_PROXY` |
  | `IPSHARKK` | IpSharkk | Residential proxy | `IPSHARKK_PROXY` |
  | `IPVANISH` | IPVanish | Consumer VPN | |
  | `JAGUAR` | Jaguar | Residential proxy | |
  | `KKOIP` | KKOIP | Residential proxy | |
  | `KOCERROXY` | KocerRoxy | Residential proxy | |
  | `KOOKEEY` | Kookeey | Proxy network | `KOOKEEY_PROXY` |
  | `LEMONLABS` | Lemon Labs (LemonClub) | Residential proxy | `LEMONCLUB_ISP`, `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_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_MOBILE` |
  | `NETVORTEX` | NetVortex | Residential proxy | |
  | `NEWIPNOW` | NewIPNow | Proxy network | `NEWIPNOW_DATACENTER` |
  | `NEXTPROXY` | NextProxy | Proxy network | `NEXTPROXY_ISP` |
  | `NIMBLE` | Nimble | Residential proxy | `NIMBLEWAY_PROXY` |
  | `NIUPROXY` | NiuProxy | Residential proxy | |
  | `NODEMAVEN` | NodeMaven | Proxy network | `NODEMAVEN_ISP`, `NODEMAVEN_MOBILE`, `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` |
  | `NULLVAULT` | NullVault | Residential proxy | |
  | `OCULUSPROXIES` | Oculus Proxies | Residential proxy | `OCULUSPROXIES_DATACENTER`, `OCULUSPROXIES_ISP`, `OCULUSPROXIES_SNEAKER`, `OCULUSPROXIES_TICKET` |
  | `OPENAI` | OpenAI | Crawler / agent | `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` |
  | `PLAINPROXIES` | PlainProxies | Proxy network | `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` |
  | `PROTONVPN` | Proton VPN | Consumer VPN | |
  | `PROXIESFO` | Proxies.fo | Residential proxy | `PROXIES_FO` |
  | `PROXIWARE` | Proxiware | Proxy network | `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_ISP`, `PROXY_SELLER` |
  | `PROXYSHARD` | ProxyShard | Proxy network | `PROXYSHARD_PREMIUM` |
  | `PROXYSIO` | Proxys.io | Proxy network | |
  | `PROXYSTORE` | ProxyStore | Proxy network | `PROXYSTORE_ISP` |
  | `PROXYWING` | ProxyWing | Residential proxy | `PROXYWING_PREMIUM`, `PROXYWING_STANDARD` |
  | `PSIPHON` | Psiphon | Consumer VPN | |
  | `PUREVPN` | PureVPN | Consumer VPN | `PUREVPNPROXY` |
  | `QUANTUMPROXIES` | Quantum Proxies | Proxy network | `QUANTUMPROXIES_ISP` |
  | `RAPIDSEEDBOX` | RapidSeedbox | Proxy network | |
  | `RARECLOUD` | RareCloud | Proxy network | `RARECLOUD_ISP` |
  | `RAYOBYTE` | Rayobyte | Residential proxy | `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_MOBILE` |
  | `RSOCKS` | RSOCKS | Residential proxy | |
  | `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 | |
  | `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 | |
  | `V6PROXIES` | V6Proxies | Proxy network | |
  | `VANTAGE` | Vantage Proxies | Residential proxy | `VANTAGEPROXIES_APEX`, `VANTAGEPROXIES_CORE`, `VANTAGE_CORE` |
  | `VAULTPROXIES` | VaultProxies | Residential proxy | |
  | `VIBEPROXIES` | VibeProxies | Residential proxy | `VIBEPROXIES_PREMIUM` |
  | `VITALPROXIES` | VitalProxies | Proxy network | `VITALPROXIES_BRIGHTDATA` |
  | `VMPARC` | VMP Arc | 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 | |
  | `WEBSHARE` | Webshare | Proxy network | |
  | `WINDSCRIBE` | Windscribe | Consumer VPN | |
  | `WIREDPROXIES` | WiredProxies | Proxy network | `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` |
  | `ZSCALER` | Zscaler | Enterprise egress | |
</Accordion>

```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, 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.

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.