Proxies

Proxies in TelegramOS: supported types, pairing rules, the connectivity test, sticky-session recovery and traffic.

Every account in your workspace connects through its own dedicated proxy. The proxy provides both IP diversity (reducing the risk of Telegram linking accounts) and a stable transport layer.

Proxy types

MTProto proxies are not supported. Proxies come from two sources: rental proxies allocated to you from the platform pool, and your own proxies (you supply endpoint and credentials).

You can bulk-import your own proxies: up to 100 per request, sent as a JSON list.

Pairing rules

• One proxy per account, strictly. An account holds at most one proxy and a proxy serves at most one account. Assigning a proxy that is already held by an active or warming account is refused (409).
• A rented account cannot be re-pointed to a different rental proxy.

Connectivity test

Run the test on demand with POST /api/proxies/{id}/check, or when you create a proxy with test_on_create=true (off by default). The test has three steps:

1. Resolve the proxy host and require a public IP. Private, loopback, link-local, multicast and reserved addresses fail the test.
2. Send one GET to http://api.ipify.org through the proxy.
3. Record the result: reachable or unreachable, the exit IP and the latency.

A failed test only records the result. Nothing is quarantined, and the platform does not retest on a schedule; run the check again after you fix the endpoint.

An account whose proxy is unreachable is retried by error recovery: after 30 minutes, then with a doubling delay, up to 5 attempts.

IP-leak check at worker start

Every time an account's worker starts, an offline leak check confirms that the proxy host is not the server's own IP. If it is, the account is paused with pause_reason=ip_leak.

Private address ranges

The connectivity test rejects a proxy host that resolves to:

• 10.0.0.0/8
• 172.16.0.0/12
• 192.168.0.0/16
• 127.0.0.0/8
• 169.254.0.0/16
• multicast and reserved addresses

A match only fails the test.

Sticky-session recovery and rotation

There is no scheduled rotation. Rental proxies keep a sticky session, and the worker replaces it only when the exit looks dead:

• When 4 or more connection attempts for an account all fail within 15 minutes, the rental proxy's sticky session id is swapped. The account gets a new exit IP with the same credentials.
• At most once per 30 minutes per account, and at most 10 accounts per sweep.
• Suppressed while more than 30% of accounts are failing. That is treated as an outage, not a proxy problem.
• If the account is still failing after 6 hours, it is paused with reason proxy_unreachable.

Manual rotation (POST /api/proxies/{id}/rotate) is available for your own proxies only. It is refused for rental proxies.

Traffic quotas

Each rental proxy bundle includes 50 MB of traffic per month.

Your own proxies are not metered by the platform.

FAQ

Can I use the same proxy for two accounts? No. One proxy per account. A proxy already held by an active or warming account is refused (409).

What happens when a rental proxy stops working? The worker swaps the sticky session for a new exit IP (see Sticky-session recovery). If the account keeps failing for 6 hours, it is paused as proxy_unreachable.

Can I bring my own proxy for a rental account? No. A rented account only takes a rental proxy; pairing it with your own proxy is refused (403).

Can an owned account use a rental proxy? Yes, if that rental proxy is allocated to you.

How do I check my current proxy's IP? Run the connectivity test. It records the exit IP and the latency.