> ## Documentation Index
> Fetch the complete documentation index at: https://figranium.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Proxy Rotation
Figranium includes a robust proxy management system to evade IP-based blocking. You can configure proxies globally or enable rotation on a per-task basis.
## **Configuring Proxies**
Navigate to **Settings > Proxies** to manage your proxy list.
### **Adding a proxy**
Click **Add Proxy** and enter the details:
* **Server**: The proxy address (e.g., `http://192.168.1.5:8080`, `socks5://10.0.0.5:1080`).
* **Username/Password**: Optional credentials for authentication.
* **Label**: A friendly name (e.g., "US Residential").
The **Add Proxy** button remains disabled until you provide a server address. When you click it, a loading spinner appears and the button disables to prevent duplicate submissions while the proxy is being saved.
Proxy server addresses are validated against the SSRF blocklist. Addresses that resolve to private or internal networks (such as `localhost`, `127.0.0.1`, or `169.254.169.254`) are rejected unless you set `ALLOW_PRIVATE_NETWORKS=true`. See [Security best practices](/docs/security) for the full list of blocked ranges.
### **Importing Proxies**
You can bulk import proxies from a text file. Click the **Import** button and select a file containing one proxy per line. Supported formats:
* **URL**: `http://1.2.3.4:8080` or `socks5://user:pass@10.0.0.5:1080`
* **host:port**: `1.2.3.4:8080`
* **host:port:user:pass**: `1.2.3.4:8080:myuser:mypass`
Lines can also be separated by commas or semicolons. Duplicate server addresses are merged automatically — if an imported proxy matches an existing one, the existing entry is updated.
Each proxy in the import is validated individually against the SSRF blocklist. If any entry points to a restricted address, the entire import is rejected. See [Security best practices](/docs/security) for blocked ranges.
### **Rotating pool proxies**
Some proxy providers give you a single gateway address that rotates through a pool of IPs on each request. You can mark a proxy as a **rotating pool** to track this in Figranium.
When adding or editing a proxy, enable the **Rotating pool** checkbox. You can optionally provide an **estimated pool size** — the approximate number of IPs behind the gateway. This is purely informational and appears as a badge next to the proxy in the list (for example, "Pool (\~500)").
Rotating pool proxies work the same as regular proxies for rotation and execution. The flag helps you distinguish single-IP proxies from pool gateways when managing a mixed proxy list.
## **Rotation Strategies**
Figranium supports two rotation modes:
1. **Round-Robin**: Cycles through the list sequentially (Proxy 1 -> Proxy 2 -> ...). This ensures even usage.
2. **Random**: Picks a random proxy from the list for each execution.
### **Default Proxy**
You can designate a specific proxy as the "Default". This proxy will be used for all tasks unless rotation is explicitly enabled.
### **Include Host IP**
You can choose whether your server's own IP address should be included in the rotation pool. This is useful for testing or when running on a residential connection.
## **Enabling Rotation in Tasks**
In the **Task Editor**, enable the **Rotate Proxies** checkbox.
* When enabled: The task will use a proxy from the rotation pool according to the strategy.
* When disabled: The task will use the **Default Proxy** (if set) or the **Host IP**.
## **API Management**
You can also manage proxies via the API:
* `GET /api/settings/proxies`: List all proxies.
* `POST /api/settings/proxies`: Add a proxy.
* `POST /api/settings/proxies/import`: Bulk import proxies.
* `PUT /api/settings/proxies/:id`: Update an existing proxy.
* `POST /api/settings/proxies/rotation`: Update rotation settings.
All proxy write endpoints validate the server address against the SSRF blocklist. If the address is restricted, the API returns a `400` status with an `INVALID_URL` error code.