Documentation

Quickstart

SIMSwarm is an ordinary forward proxy. There is no SDK to install and no API call to make before you can send traffic — everything is controlled through the credential you authenticate with.

Create a key in the dashboard, then send a request:

curl -x gb.simswarm.io:9000 -U "sw-live-3f9ac2:YOUR_SECRET" https://api.ipify.org
82.132.214.19

curl -x gb.simswarm.io:9000 -U "sw-live-3f9ac2:YOUR_SECRET" https://api.ipify.org
92.40.176.88   # different SIM, different carrier, different city

That is the entire integration. Point your existing crawler at the same host and port and every request it makes will leave from a different British mobile IP.

Endpoints

Authentication

Standard proxy basic auth. The username carries your key and your targeting rules, separated by hyphens; the password is your secret.

# structure
<key>[-param-value]...  :  <secret>

# plain — rotate on every request
sw-live-3f9ac2:YOUR_SECRET

# Manchester, EE only, held for ten minutes
sw-live-3f9ac2-city-manchester-carrier-ee-session-k3p9-ttl-10m:YOUR_SECRET

Prefer not to put secrets in a proxy URL? Add up to 20 IP addresses or CIDR ranges to the allowlist on a key and authenticate by source address instead. Targeting then moves to the X-Swarm-Target request header.

Targeting parameters

Unknown parameters are rejected with 407 rather than silently ignored — a typo in -city-machester- should fail loudly, not quietly send your crawl to Cornwall.

Rotation & sessions

Rotate on every request

The default. Each new TCP connection is dispatched to whichever healthy SIM matches your targeting and has the least recent contact with the host you are calling. Nothing is sticky, including within a keep-alive pool — every fresh connection gets a fresh exit.

Sticky sessions

Add a session token when the target needs continuity — a login, a basket, a paginated result set behind a cursor.

sw-live-3f9ac2-session-order-88213-ttl-20m:YOUR_SECRET

The SIM is reserved for that token until the TTL expires or you stop using it. If the SIM drops off the network mid-session, the gateway assigns a replacement and sets X-Swarm-Session-Broken: 1 so your code can decide whether to restart the journey.

Forcing a change

Change the session token. There is no rotation endpoint to call and no cooldown to wait out — a new token is a new exit.

Response headers

Every response carries diagnostics from the gateway. They are stripped from anything you forward on.

X-Swarm-Exit:            82.132.214.19
X-Swarm-Carrier:         ee
X-Swarm-City:            manchester
X-Swarm-Net:             5g
X-Swarm-Sim:             sim_7f31c9        # stable id, useful for your own scoring
X-Swarm-Attempts:        1                 # SIMs tried before this response
X-Swarm-Bytes:           184213            # billed bytes for this request
X-Swarm-Session-Broken:  0

Errors & retries

The gateway already retries up to twice onto fresh SIMs when a connection fails or a SIM drops mid-flight, and those attempts are never billed. Layering aggressive client-side retries on top mostly multiplies load against the target — set RETRY_TIMES = 2 or equivalent and let us do the rest.

Usage API

Bearer-authenticated JSON at api.simswarm.io. Everything on the dashboard is available here.

curl -H "Authorization: Bearer sk_live_…" \
  "https://api.simswarm.io/v1/usage?from=2026-08-01&to=2026-08-31&group_by=key"

{
  "period":   { "from": "2026-08-01", "to": "2026-08-31" },
  "bytes":    161061273600,
  "gb":       150.0,
  "band":     "scale",
  "rate_gbp": 1.50,
  "cost_gbp": 225.00,
  "requests": { "total": 812443, "ok": 782118, "blocked": 21990, "failed": 8335 },
  "keys": [
    { "key": "sw-live-3f9ac2", "gb": 121.4, "success_rate": 0.968 },
    { "key": "sw-live-91be07", "gb":  28.6, "success_rate": 0.931 }
  ]
}

Other endpoints: /v1/keys to mint and cap sub-account keys, /v1/pool for live SIM counts by city and carrier, and /v1/webhooks for spend and success-rate alerts.

Practical advice

• Give it time. Mobile is not datacentre. Set client timeouts to 30 seconds or more — a 5-second timeout will fail perfectly good requests and still bill you for the bytes already moved.
• Use sessions for journeys, not for pages. One session per checkout flow, not one per crawl. Long-lived sessions on a single SIM look far more like a bot than rotation does.
• Do not pin a city unless the data changes by city. Targeting shrinks the pool you can draw from, which raises queueing at peak. Store locators and regional pricing justify it; a generic product page does not.
• Score by SIM, not by IP. CGNAT means the same address can serve different SIMs and the same SIM can change address. X-Swarm-Sim is the stable identifier.
• Fetch what you need. You are billed on bytes, so blocking images, fonts and video in a headless browser typically cuts your bill by 60–80%.

Limits & fair use

No cap on concurrent connections, threads or requests per second on paid accounts. Trials are limited to 20 concurrent connections. Single requests over 512 MB are rejected — talk to us if you are pulling large files.

Prohibited outright: credential stuffing, card testing, fraud, malware distribution, CSAM, and any traffic directed at UK critical national infrastructure. Accounts above £500 a month are KYC-verified. We respond to abuse reports within one business day and can trace any exit IP back to the account, key and SIM that used it.