Documentation

SIMSwarm gateway documentation

One endpoint, targeting encoded in your credentials, and a different mobile exit on every request.

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.

Once your account is approved we issue your credentials. Then send a request:

curl -x gb.simswarm.io:9000 -U "swarm11072:YOUR_SECRET" https://api.ipify.org
82.132.214.19

curl -x gb.simswarm.io:9000 -U "swarm11072: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 account name and your targeting rules, separated by hyphens; the password is your secret.

# structure
<account>[-option-value]...  :  <secret>

# plain — rotate on every request
swarm11072:YOUR_SECRET

# Manchester, EE only — still rotating on every request
swarm11072-city-manchester-carrier-ee:YOUR_SECRET

IP whitelisting

Prefer not to put secrets in a proxy URL? If you have a dedicated port, we can whitelist your source addresses and you connect with no login at all — plain HTTP with no Proxy-Authorization, or SOCKS5 offering “no authentication”. Your pool, rotation, limits and metering are unchanged.

Two things worth knowing. The shared port on 9000 never honours a whitelist — whitelisting only applies to your own dedicated port. And if you do send a login it is always honoured and must be correct, which is how whitelisted customers still get targeting: send the username with its targeting tokens as normal.

Targeting parameters

Beyond that, the gateway gives each request up to three attempts on different exits. An exit that has not answered within three seconds is abandoned and the next one dialled. Those retries are ours, not yours — you do not need to layer aggressive client-side retries on top, and doing so mostly multiplies load on the target.

Account & usage API

Bearer-authenticated JSON at app.simswarm.io, so you can reconcile our figures against your own rather than taking an invoice on trust.

curl -H "Authorization: Bearer sws_live_…"   "https://app.simswarm.io/v1/usage?from=2026-09-01&to=2026-09-30"

{
  "period": { "from": "2026-09-01", "to": "2026-09-30" },
  "bytes":  161061273600,
  "gb":     150.0,
  "by_day": [ { "date": "2026-09-01", "gb": 4.9 }, … ]
}

/v1/account returns your endpoint, your dedicated port if you have one, your whitelisted addresses, your daily cap and your per-request size limit.

Fetch API

Optional, and a different shape of product: give us a URL, get the page body back. We handle the exit, the retries and the browser-shaped TLS handshake, so you are not maintaining a scraping client at all.

curl "https://app.simswarm.io/v1/fetch?token=sws_live_…&url=https%3A%2F%2Fwww.example.co.uk%2Fproduct%2F123&country=gb"

The response body is the target’s. The headers tell you what happened:

X-Target-Status:   404      # the TARGET's code, not ours — a 404 means discontinued
X-Swarm-Result:    ok
X-Swarm-Attempts:  1
X-Swarm-Ms:        640
X-Swarm-Billed:    1

• Only successful fetches are billed. Blocks, timeouts and errors are logged free. Up to five attempts, a different mobile exit each time.
• Our own status codes are separate from the target’s: 502 blocked, 504 upstream error, 400 a bad request, 401 a bad token.
• Pass your own headers through as X-Fetch-<Header> — X-Fetch-Cookie, X-Fetch-Accept-Language.
• The client presents a real browser’s TLS fingerprint and HTTP/2 framing, and keeps a cookie jar per host, which is what gets several anti-bot systems to answer at all.
• JavaScript rendering is not available yet. Pages whose prices are drawn client-side will come back as the shell the server sent.

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.
• Design for statelessness. Every request gets a different IP, so anything that depends on continuity — a login, a basket, a cursor tied to a session cookie — will not work today. Fetch pages that stand on their own, and keep any state your side.
• 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.
• Do not score exits by IP. CGNAT means one address can serve many subscribers, and a mobile IP can rotate underneath you mid-connection. Judge a crawl on whether the page came back with the content you expected, not on which address delivered it.
• 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

Three limits are set per account, and all three are visible to you on /v1/account:

• Concurrent connections. Agreed with you when the account is set up and raised on request — tell us how many workers you intend to run.
• Daily data cap. Reaching it returns 429 until midnight UTC. It exists so a runaway crawl cannot spend your month in an afternoon.
• Per-request size limit. Optional, returns 413. Useful protection against accidentally pulling a video through mobile data.

Accounts are issued to registered companies for commercial data collection. Personal use, resale of raw proxy access, social media automation, bulk account creation and limited-release purchasing bots are outside the terms and will end the account.

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 and SIM that used it.