Skip to main content
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.
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.

​
POST /v1/agents/ip-rotation

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.
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.
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:
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.