Skip to main content
Most proxy providers give you an IP and hope it works. SOAX works differently. We built a system where you describe what you need (where, how, for how long, what happens when something breaks) and the platform handles the rest. You don’t manage IPs directly. You set rules, and the system executes them predictably, even at high concurrency and at scale. This page explains the building blocks that make this work: packages, sessions, rules, and bindings. Understanding these concepts will help you get more out of SOAX than just rotating through IPs.

​
Packages

A proxy package is your entry point to the proxy network. It’s where credentials, limits, and access controls live. When you create a package in the dashboard, you’re setting up a self-contained unit of proxy access. Each package has its own:
  • Package key for authentication
  • Network types (residential, mobile, or both)
  • Traffic limits (optional, set by the organization owner)
  • RPS and connection limits controlling throughput
  • IP allowlist for IP-based authentication
  • Assigned users who can use the package
Packages exist so you can separate and control how different teams or use cases consume proxy traffic. For example, you might create one package for your scraping pipeline with residential-only access and a 500GB limit, and another for your QA team with mobile enabled and no limit. All usage is tracked per package, which means you can see exactly how much traffic each use case or team is generating. Credits are consumed from your organization’s shared pool, but packages control who can spend them and how. For more on managing packages, see Package Management.

​
Sessions

A session groups related requests and gives them a shared context. Without a session, every request is independent. The system picks a new node each time, with no memory of what happened before. This is rotating mode, and it’s the right choice for high-volume work where you don’t need IP continuity. But many workflows need continuity. You might need to log in, navigate to a page, and then scrape it. Or you might need to maintain the same IP for a few minutes while you collect data from a multi-page flow. That’s what sessions are for. When you create a session (by adding a session parameter to your connection string), the system binds your session to a node and keeps using that node for subsequent requests. All the rules you set apply consistently across every request in that session. Changes to the node only happen when your rules allow it. 
country-us-session-job1:YOUR_PACKAGE_KEY@proxy.soax.com:1337
You pick the session ID (letters, digits, and underscores, up to 32 characters). The rules are set on the first request and apply for the lifetime of the session — if you send the same session ID later with different rules, the request is rejected with 409 SESSION_PARAMS_MISMATCH. To change rules, use a new session ID. Sessions expire after 60 seconds of inactivity. The key principle: sessions give you controlled continuity. You’re not locked to a random IP and hoping it stays up. You’re telling the system what behavior you need, and it maintains that behavior across requests.

​
Rules

Rules are what set SOAX apart from most proxy providers. Instead of giving you a few toggles (country, rotation time), SOAX uses a composable rules system with four independent categories. Each category answers a different question about how your requests should be handled:

​
Filtering rules: which nodes can be used?

Filtering rules constrain the pool of eligible nodes based on their characteristics. You can filter by country, region, city, ISP, ASN, zip code, or network type. These filters are enforced continuously. If you’re in a session and the bound node stops matching your filters (for example, the node’s IP is reclassified from US to JP), the binding becomes invalid and the system replaces it. 
country-us-city-new_york-isp-comcast

​
Routing rules: how does the system choose between eligible nodes?

Once the system knows which nodes are eligible, routing rules influence which one it picks. The available option is prefer-lookalike, which tells the system to favor nodes with similar characteristics to the previous one when it needs to select a replacement. This matters when your node gets replaced (due to rotation, error, or reclassification). Without prefer-lookalike, you might jump from a Comcast IP in New York to a Verizon IP in Texas. With it, the system tries to find another Comcast IP in New York first. 
prefer-lookalike

​
Rotation rules: when is the system allowed to change the node?

Rotation rules control when the current node can be replaced during a session. You can rotate after a set number of seconds (rotate-timed_N, max 1 week, accepts s/m/h suffixes) or after a set number of requests (rotate-requests_N, max 1,000,000). Without a rotation rule, a session keeps the same node until it encounters an error or its filters stop matching. 
rotate-timed_300
rotate-requests_50

​
Error handling rules: what happens when something goes wrong?

Error handling rules define how the system reacts to infrastructure failures (node goes offline, connection refused, timeout). You have three options: replace the node with a new one (default), retry the request on the same node a set number of times before replacing (max 10), or fail immediately and return the error to your client. 
onerror-replace
onerror-retry_3
onerror-fail
SOAX works at the transport layer, so the failures it can act on are infrastructure failures — node offline, connection refused, timeout. It can’t see HTTP status codes or soft blocks inside an HTTPS tunnel, so target-side responses (403, 429, CAPTCHA pages) are your application’s problem to detect and handle.

​
Why this matters

These four categories are independent. You can combine any filtering rule with any routing preference, any rotation trigger, and any error handling strategy. They compose together in a single connection string: 
country-us-city-new_york-session-job1-rotate-timed_300-onerror-retry_3-prefer-lookalike
That string says: use a US node in New York, maintain a session called “job1”, rotate to a new node every 300 seconds, retry 3 times on the same node before replacing on error, and when you do replace, prefer a node with similar characteristics. Most proxy providers make you choose between rotating and session-based connections and give you a country dropdown. SOAX lets you describe exact behavior for every scenario your requests might encounter. The system then executes that behavior deterministically, whether you’re sending 10 requests or 10 million.

​
Bindings

A binding is the link between a session and a node. When your session’s first request is processed, the system selects a node that matches your filtering rules and creates a binding. That node handles all subsequent requests in the session until something causes the binding to change. A binding can change when:
  • A rotation rule triggers (timed or request-count)
  • The node fails and error handling replaces it
  • The node no longer matches your filtering rules
When a binding changes, the system selects a new node using your filtering and routing rules, and creates a new binding. The session continues without interruption. You normally don’t interact with bindings directly. They’re managed by the rules you set. But there’s one exception: bind-node. When you use bind-node, you’re telling the system to lock the session to exactly one node. No rotation, no automatic replacement. If that node goes offline, your requests fail with an explicit error (503 BOUND_NODE_FAILED) instead of silently switching to a different node. This is useful for workflows where using a different node mid-session would cause problems (for example, maintaining a logged-in state on a target that fingerprints by IP). bind-node requires a session and is incompatible with rotate-timed_N, rotate-requests_N, onerror-replace, and prefer-lookalike. You can pair it with onerror-retry_N to retry on the same node before failing.

​
Nodes and IPs

A node is a real device in the SOAX network that executes your requests. It has a physical location, a network connection, and an IP address that the target website sees. Nodes are not permanent. They’re real devices on real networks, which means they can change IP, go offline, or shift characteristics over time. SOAX is designed to handle this as a normal operating condition, not as an exception. This is why continuity in SOAX doesn’t live at the IP level. It lives in sessions and bindings. Your session’s rules define what behavior you need, and the system delivers it using whatever nodes are currently available and eligible. If a node changes or disappears, the rules handle what happens next. This is a deliberate design choice. Systems that promise IP stability are making guarantees they can’t always keep, especially at scale. SOAX instead gives you explicit control over what happens when things change, so your workflows stay predictable.

​
How it all fits together

  1. Your organization has a credit pool and one or more packages.
  2. Each package defines who can connect, what network types are available, and what limits apply.
  3. When you send a request, you include rules in your connection string that describe what you need.
  4. If you include a session parameter, the system creates a session and binds it to a node that matches your rules.
  5. The binding persists across requests, changing only when your rotation, error handling, or filtering rules require it.
  6. If you don’t include a session, each request is independent and gets a fresh node every time.
The result is a system where you describe behavior, not infrastructure. You don’t need to know which specific node or IP you’re using. You just define the rules, and the system handles the rest.

​
Next steps

Quickstart

Make your first request in under 5 minutes.

Residential proxies

Full parameter reference for residential proxy rules.

Mobile proxies

Full parameter reference for mobile proxy rules.

Authentication

How to set up credentials and connect.