API — Port Pool

Open and manage port pools — batches of ports opened from a proxy list for large, concurrent jobs — then export the results.

Open a pool

NoteThe Port Pool endpoints live under the /scraper path for backward compatibility — it is the same feature as the + Port Pool button in the dashboard.

POST /api/v1/scraper/tasks Auth required

Opens a port pool from a proxy list.

Parameter	Type	Required	Description
`name`	`string`	Yes	Pool name.
`source`	`object`	Yes	Where the proxy list comes from: kind is "file", "url" or "inline"; location is the path or URL; content carries the list itself for "inline". Optional refresh_interval re-reads the source (minimum 30s, default 10m), and default_scheme applies to bare host:port entries (default socks5).
`target`	`int`	Yes	How many ports the pool should open.
`port_lo`	`int`	No	Low end of the local port range the pool may use.
`port_hi`	`int`	No	High end of the local port range.
`protocol`	`string`	No	Listen protocol of the pool ports: "socks5" (default) or "http".
`up_policy`	`object`	No	How often a port switches upstream. mode is "requests" (every n connections), "minutes" (every n minutes) or "on_error" (hold the proxy until the client is served an error). Default: every request.
`fp_policy`	`object`	No	How often a port switches identity, in the same shape and with the same three modes. Default: every 10 requests.
`device`	`string`	No	Browser family for the pool identities, for example "chrome". See GET /api/v1/scraper/device_matrix.
`device_os`	`string`	No	Operating system for the pool identities, for example "windows".
`profile_source`	`string`	No	Where identities come from: "auto" generates them on the fly, "db" takes them from the curated database.
`auto_ua`	`bool`	No	Pick each identity from the request User-Agent instead of the pool setting.
`spoof_headers`	`bool`	No	Rewrite outgoing headers to match the current browser. Recommended for scrapers; on by default.
`connect_timeout_seconds`	`int`	No	Cap on a single connect attempt for every port in the pool, in seconds. Default 5.
`request_timeout_seconds`	`int`	No	Silence budget for every port in the pool, in seconds: the connect phase including retries, then the wait for the first byte. Default 30; 0 removes the limit.
`idle_timeout_sec`	`int`	No	Idle timeout on a connection of a pool port, in seconds: the connection is closed after this long with no bytes. Default 60. Distinct from idle_seconds, which closes the port itself. The former name request_timeout_sec is still accepted when a pool saved by an earlier version is read.
`idle_seconds`	`int`	No	Port lifetime, in seconds. A pool keeps its ports open by default (0).

Example (curl)

curl -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"tiktok-pool","target":100,"port_lo":20000,"port_hi":30000,
        "protocol":"socks5",
        "source":{"kind":"file","location":"C:/proxies.txt"},
        "up_policy":{"mode":"requests","n":1},
        "fp_policy":{"mode":"requests","n":10},
        "connect_timeout_seconds":5,"request_timeout_seconds":30}' \
  http://127.0.0.1:8891/api/v1/scraper/tasks

NoteThe on_error mode keeps the upstream proxy and the identity for as long as they work, and rotates them once the client is served a 4xx or 5xx response. 2xx and 3xx count as success, so redirects and cached responses do not trigger a rotation. What counts is the status YOUR CLIENT receives: if a request met a challenge and the challenge was handled so that the client got 200, no error occurred. A burst of failures from one dying proxy costs a single rotation, not one per request. The mode is available to port pools only, and needs a port that inspects traffic — on a port opened with tls_passthrough there is no HTTP status to observe.

List & stop pools

GET /api/v1/scraper/tasks Auth required

Lists all port pools and their progress.

DELETE /api/v1/scraper/tasks/{id} Auth required

Stops a pool and closes its ports.

POST /api/v1/scraper/tasks/{id}/test Auth required

Tests the pool's proxy list.

GET /api/v1/scraper/tasks/{id}/config Auth required

Returns the stored configuration of a pool, in the shape POST /api/v1/scraper/tasks accepts.

GET /api/v1/scraper/device_matrix Auth required

Lists the browser and operating-system combinations a pool can be built from.

POST /api/v1/scraper/probe Auth required

Checks a proxy source before a pool is started: reachability of the entries, DNS and IPv6 leaks, UDP support, and how many usable proxies the list yields.

Export results

GET /export/{token}/proxies.txt No auth

Downloads a pool's ports as a plain-text proxy list. Access is granted by the token in the URL, so no API key is needed.

Example (curl)

curl http://127.0.0.1:8891/export/TASK_TOKEN/proxies.txt