CAPABILITY · PACING
Pacing that protects your account, not our servers
A per-account, per-host governor caps how fast one identity may be re-poked and puts it on cooldown after a ban signal — answering 429 with Retry-After instead of burning the account.
429 + Retry-After · reason: cooldown | min_gap | windowCapability
Inside account cadence governor
This is not a rate limit on our service — that exists separately. It is a governor that protects the customer's own account from the TARGET's bot detection. A runaway loop hammering one login is how an account gets flagged, and the flag outlives the loop. So a run that is going too fast for the identity it is using is refused before any credit is reserved, and an identity that just got pushed back on is put on cooldown rather than re-poked.
Keyed on the identity, not the tenant
The governor keys on the run's `account` label (or its `sessionKey`) plus the target host. A run with neither has no persistent identity to protect, so the governor is a no-op for it.
A minimum gap and a rolling window
Two constraints: a minimum interval between runs on the same identity, and a cap on runs per identity per host in a rolling window. Exceeding either is a 429 naming which one.
Cooldown after a ban signal
When a run ends blocked, rate-limited or challenged, the account is put on cooldown so the next run defers rather than re-poking a flagged identity. An ordinary 2FA park is NOT a ban signal.
Refused runs are free
The check happens before the credit reserve. A throttled call creates no run row and costs nothing — it returns 429 with a Retry-After header and a machine-readable reason.
How it works
The mechanism, in execution order
4 stages, in the order the runtime performs them — not a summary of them.
- 1Derive the identityThe account label, else the sessionKey, plus the target host. No identity means no governing.
- 2Admit or deferThe governor checks the cooldown, the minimum gap and the rolling window, and either admits the run and bumps the counter, or returns a retry-after.
- 3Refuse cheaplyA deferral is a 429 with Retry-After and reason (cooldown | min_gap | window), recorded in the audit log, with nothing reserved.
- 4Back off on a push-backA run that ends blocked, rate-limited or challenged stamps a cooldown on the account so the next attempt waits.
In practice
A call you can paste and run
The reason tells you whether to slow down, spread out, or wait for a flagged identity to cool off.
HTTP/1.1 429 Too Many Requests
retry-after: 42
content-type: application/json
{
"error": "account rate limit — this account is being paced to avoid target bot-detection",
"reason": "min_gap",
"retryAfterMs": 41500
}
# reason: "cooldown" — the account was pushed back on recently
# "min_gap" — too soon after the last run on this identity
# "window" — too many runs on this identity/host in the window
# Nothing was reserved. No run row was created. This response is free.- Derive the identitydone
- Admit or deferrunning
- Refuse cheaplyqueued
- Back off on a push-backqueued
What it costs, how to switch it on
Priced from the same rate card the API serves
Every credit figure on this page is read from the rate card behind GET /api/v1/pricing — it is not typed into the copy, so it cannot drift from what you are billed.
Free — a governed run is never reserved
The cadence check runs before the credit reserve, so a deferred run creates no row and charges nothing. It is recorded in the audit log so you can see the pacing decisions, but a 429 here never costs a credit.
Turning it on
- 1Give your runs an identityPass `account` (or an explicit `sessionKey`). Without one, there is no identity to pace and the governor does nothing.
- 2Honour Retry-AfterThe header is in seconds and `retryAfterMs` is in the body. Backing off is the whole point; retrying immediately defeats it.
- 3Branch on the reason"min_gap" means space out; "window" means you are doing too much on one identity per hour; "cooldown" means the target already pushed back.
- 4Spread across accountsSeveral labelled logins per host each get their own budget, which is the legitimate way to raise throughput.
At a glance
The contract, in the fewest rows that say it
| Property | Twin Browser |
|---|---|
| Scope | Per account (or sessionKey) × host |
| Response | 429 + retry-after header |
| Reasons | cooldown · min_gap · window |
| Ban signals | blocked · rate-limited · challenged |
| Not a ban signal | A HITL 2FA park |
| Failure mode | Fails OPEN — admits the run |
Limits
Where it stops, and what it deliberately does not do
A capabilities page with no limits section is a brochure. These are the ceilings, the defaults that will surprise you, and the things this capability is not.
Limits and defaults
- The governor only sees runs that carry an identity. Anonymous runs are ungoverned by construction.
- It fails OPEN. A missing migration, a missing key or a database hiccup admits the run — a governor must never take runs down harder than the target would have.
- Enforcement is globally switchable off by the deployment, so treat it as a safety net rather than a contract.
- The window and gap are deliberately generous defaults; they catch a runaway loop, not ordinary use.
What it does not do
- It does not protect our service. That is the edge rate limiter, and it is a different thing with a different response.
- It does not pace by tenant. Two accounts on the same host have independent budgets, because they are independent identities.
- It does not treat a 2FA park as a ban. An expected, resumable auth wall is not the target flagging you.
- It does not queue the run for later. A deferral is a refusal with a Retry-After — the retry is yours to make.
FAQ
Questions about account cadence governor
Is this a rate limit on my API key?
Do I pay for a run it defers?
What puts an account on cooldown?
What happens if the governor itself is unavailable?
Keep reading
The rest of the platform
The capabilities this one works with, the tools that expose it, the guides that use it end to end, and the vocabulary behind it.
Egress, geo & locale
A single `country` field sets the residential exit AND the browser locale and timezone, so a site cannot serve a different language than the exit you asked for — or bring your own proxy and keep both.
Stealth tier
A full desktop browser profile — real Chrome, human-calibrated timing, residential egress — behind a plan gate and an explicit authorization attestation, billed per success.
Connected accounts & handoff
Mint a single-use link, your end user completes the sign-in in a hosted browser, and the captured session makes every later run already logged in — with no password anywhere.
Tools that expose it
Put your agent to work. Keep the decision.
Start free. Hand your agent a goal on a site you authorize, set the guardrails, and let the first successful run compile the skill every run after it replays.