Proxy Rotation Manager — Pool Health Check & Rotating Batch Fetch

Point this actor at a proxy pool and it does two things: health-checks every proxy against a test URL (latency, exit IP, up/down), then — if you give it target URLs — fetches your batch through the healthy proxies with automatic rotation and retry-on-next-proxy. It is a reliability tool for anyone who runs a proxy pool and wants to know which endpoints are alive, how fast they are, and have their requests spread across the good ones instead of hammering a dead node.

Bring your own proxies (proxyUrls) or use Apify Proxy (billed to your account). Proxy passwords are masked in every output row and log line — raw credentials are never emitted.

Why agents use this actor

• Deterministic typed output. Every row matches the published dataset schema; a type field (proxy-health / target-fetch) tells the two row kinds apart. Every field is nullable, so partial results never break your pipeline.
• Per-event pricing. You pay per proxy checked and per target fetched — predictable before the run starts.
• Your proxy, your bill. All proxy traffic runs on your own proxyUrls or your Apify Proxy configuration. This actor never carries proxy cost.
• Credential-safe. Passwords are stripped to *** everywhere. Nothing this actor writes contains a usable secret.
• Clear error semantics. No proxies, or all proxies dead, fails fast with a descriptive message and exit code 1 — never a silent empty dataset. A single dead proxy is recorded as healthy:false and the run continues.

What it does

1. Phase 1 — health check. Each proxy in the pool requests testUrl. For every proxy you get a proxy-health row: masked label, HTTP status, latency, exit IP (when the test URL echoes it), and healthy. Healthy proxies are ranked fastest-first.
2. Phase 2 — rotating fetch (optional). If you pass targetUrls, each URL is fetched through the healthy pool using your rotationStrategy. If an attempt fails, it retries on the next proxy up to maxRetriesPerTarget. Each target yields a target-fetch row: final status, masked proxy used, attempt count, latency, and ok.

Rotation strategies

Strategy	Behavior
round-robin	Cycle through healthy proxies in latency order (default)
least-recently-used	Always pick the proxy idle the longest — evens out load
sticky-per-host	Pin each target host to one proxy; move on only when it fails

Input schema

Field	Type	Required	Default	Description
testUrl	string	no	https://api.ipify.org?format=json	URL each proxy is probed against. Use an IP-echo endpoint to capture exit IPs.
proxyConfiguration	object	no	—	Apify Proxy config, billed to your account. Each rotation is a distinct session.
proxyUrls	string[]	no	[]	Your own proxy endpoints (http://user:pass@host:port).
poolSize	integer	no	5	Distinct Apify Proxy sessions to form the pool. Ignored when proxyUrls is set.
targetUrls	string[]	no	[]	URLs to fetch through the healthy pool. Empty = health-check only.
rotationStrategy	string enum	no	round-robin	round-robin, least-recently-used, sticky-per-host.
maxRetriesPerTarget	integer	no	2	Extra proxies to try after the first attempt fails.
requestTimeoutMs	integer	no	30000	Per-request timeout in milliseconds.

Output schema

Two row kinds in the default dataset, distinguished by type. All fields nullable.

proxy-health (phase 1, one per proxy)

Field	Type	Description
proxyLabel	string | null	Masked proxy identifier (password → ***)
status	integer | null	HTTP status for the test URL
latencyMs	integer | null	Round-trip time in ms
exitIp	string | null	Exit IP echoed by the test URL
healthy	boolean | null	True on a 2xx/3xx response

target-fetch (phase 2, one per URL)

Field	Type	Description
targetUrl	string | null	The fetched URL
finalStatus	integer | null	Status of the final attempt
proxyUsed	string | null	Masked proxy used on the final attempt
attempts	integer | null	Proxies tried (1 = first-try success)
latencyMs	integer | null	Round-trip time in ms
ok	boolean | null	True on a 2xx/3xx response

A SUMMARY key-value record holds pool size, healthy count, the fastest proxy, and the targets requested.

Use from AI agents (MCP)

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com/?tools=apricot_blackberry/proxy-rotation-manager",
      "headers": { "Authorization": "Bearer <YOUR_APIFY_TOKEN>" }
    }
  }
}

Works in Claude, Cursor, ChatGPT connectors, and any MCP client; the input schema above is the tool's parameter schema.

Use from code

curl

curl -X POST "https://api.apify.com/v2/acts/apricot_blackberry~proxy-rotation-manager/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"proxyConfiguration":{"useApifyProxy":true,"apifyProxyGroups":["DATACENTER"]},"poolSize":3,"targetUrls":["https://httpbin.org/ip"]}'

JavaScript

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('apricot_blackberry/proxy-rotation-manager').call({
    proxyUrls: ['http://user:pass@proxy1.example:8000', 'http://user:pass@proxy2.example:8000'],
    targetUrls: ['https://example.com/a', 'https://example.com/b'],
    rotationStrategy: 'least-recently-used',
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items.filter((i) => i.type === 'proxy-health' && i.healthy));

Python

from apify_client import ApifyClient

client = ApifyClient("<YOUR_APIFY_TOKEN>")
run = client.actor("apricot_blackberry/proxy-rotation-manager").call(run_input={
    "proxyConfiguration": {"useApifyProxy": True, "apifyProxyGroups": ["RESIDENTIAL"]},
    "poolSize": 5,
    "targetUrls": ["https://httpbin.org/ip"],
    "rotationStrategy": "round-robin",
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["type"], item.get("proxyLabel") or item.get("targetUrl"), item.get("latencyMs"))

Use from automation platforms

• n8n / Make / Zapier — native Apify integration, "Run Actor", pick proxy-rotation-manager. Schedule the health check and alert when healthy drops.
• LangChain / LlamaIndex — wrap with the Apify Actor tool wrappers; the input schema becomes the tool signature.
• Apify Schedules + webhooks — run the pool health check on a cron and fire ACTOR.RUN.SUCCEEDED into your monitoring.

Pricing

Pay per event. You are charged only for work a run actually completes.

Event	When it fires
actor-start	Once per run
proxy-checked	Once per proxy health-checked
request	Once per target URL fetched successfully

Proxy bandwidth is billed separately to you by your proxy provider or by Apify Proxy on your account — this actor never carries it.

FAQ

Do you ever see or store my proxy passwords? The actor uses them to make requests, but every value it writes — dataset rows, logs, the SUMMARY record — has the password masked to ***. No output contains a usable credential.

Who pays for the proxy traffic? You do. Either your own proxyUrls (your provider bills you) or your Apify Proxy configuration (billed to your Apify account). The actor's own charge events cover only orchestration, never bandwidth.

How do I capture exit IPs? Use an IP-echo testUrl. The default (ipify) returns {"ip":"..."}; https://httpbin.org/ip returns {"origin":"..."}. Both are parsed automatically.

Can I run just the health check? Yes — leave targetUrls empty. You get one proxy-health row per proxy and nothing else.

Changelog

1.0 — Initial release. Two-phase pool health check + rotating batch fetch, three rotation strategies, retry-on-next-proxy, Apify Proxy and bring-your-own support, credential masking everywhere, per-event pricing.