For teams whose automation gets blocked
Reach the site that keeps blocking you.
Your script works locally and dies in production, because a datacenter IP and a headless fingerprint are answered differently. Twin runs authorized work from sticky residential egress, offers a full desktop browser profile when a run is actually turned away, and hands a wall no software can pass back to a human — with a link, not an error.
The problem
What this costs you today.
It ran fine on a laptop. In production it gets an interstitial, or a login page that never accepts the password, or a 403 that only appears from your cloud region. Nothing in the logs says "you look like a robot" — you get a page that is technically 200 and completely useless. So the work goes back to a person, or the team starts a fingerprinting side-project nobody asked for.
- “It works on my machine and fails from our servers.”
- “We are authorized to use this account and the site still will not let our automation in.”
- “Every fix we ship buys us two weeks before the next detection change.”
- “Our runs fail with no error we can act on.”
- Run from sticky residential egressdone
- Detect the bot wall honestlyrunning
- Retry in a desktop profilequeued
- Mint a human sign-in linkqueued
- Restore the session next runqueued
How Twin solves it
The mechanism, not a promise.
Three escalating answers, and an honest boundary at the end of them. Most runs need the first. The last one is a person, and the product says so rather than burning your credits pretending otherwise.
- 1Sticky residential egress, by defaultRuns egress through the platform proxy pool with per-account stickiness, so a session keeps a consistent network identity instead of hopping IPs mid-flow. Set `platformProxy:false` to opt out, or pass your own `proxy`.
- 2A real desktop profile when a run is turned away`stealth:true` runs the task in a full desktop browser profile with human-calibrated timing and residential egress. It requires a Pro or Enterprise plan (otherwise 403 `code:"plan_required"`) and an explicit `authorized:true` attestation, and it carries a per-success surcharge. It is not the default because most tasks do not need it.
- 3A wall that software cannot pass becomes a linkWhen a run meets a score-based defence or a challenge that persists, the result carries `code:"connect_required"` with a ready one-time `connectUrl`. Your end-user opens it, signs in by hand once, and every later run restores that session.
- 4Repeated blocks stop costing you moneyOn a host with repeated score-wall blocks the run can short-circuit to that connect response WITHOUT executing, with the credit reserve refunded and `policy.fastpath:"score-wall"` on the result — the policy engine declining to spend your credits on a wall it already knows about.
- 5A CAPTCHA on a live session has a hand-offPOST /api/v1/solve-captcha passes a live or paused session’s CAPTCHA to the solver and continues the run.
In practice
The actual call, and what it returns.
The same call, with the escalation made explicit — and the two answers that are not "it worked", both of which are actionable.
curl https://twin-browser.com/api/v1/run \
-H "Authorization: Bearer $TWIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://portal.example.com/reports",
"prompt": "open the entitlements report for this month",
"success": { "kind": "textVisible", "value": "Entitlements" },
"account": "portal-ops",
"stealth": true,
"authorized": true
}'
# → 200 { "success": true, "steps": 5, "runId": "…", "credits_charged": 10 }
# → 403 { "error": "…", "code": "plan_required" }
# stealth needs a Pro/Enterprise plan and "authorized": true.
# → 200 { "code": "connect_required",
# "connectUrl": "https://twin-browser.com/connect/…",
# "connectId": "…", "connectExpiresAt": "…" }
# the wall cannot be passed by software. Send that link to the person
# who owns the login; they sign in once, and later runs restore the
# captured session (sessionRestored: true).What this call does
- `authorized:true` is a required attestation for a stealth run and is recorded as the durable authorization artifact for that run.
- Stealth is billed like a normal run plus a per-success surcharge — you are not charged the premium for a run that did not succeed.
- Opt out of the auto-minted connect link with `connect:false` and mint your own with POST /api/v1/connect/sessions.
- A run short-circuited by the score-wall fastpath refunds its reserve and says so on the result, rather than spending credits on a wall it expects to lose to.
What it costs
Priced per action, not per seat.
The base run price does not change because a site is difficult. The premium path costs more only when it succeeds.
| Action | Credits | What you get |
|---|---|---|
| POST /run — a standard run | 10 / run | Platform sticky residential egress is included, not an add-on. |
| …with `stealth: true` | metered | The run floor plus a per-success surcharge. Pro or Enterprise plan required. |
| POST /live — watch it happen | 10 / run | Streamed frames, which is how you see what the wall actually showed. |
| POST /skills/{name}/run — replay | 1 / run | Once a flow works on a hard target, replaying it is the flat rate. |
How the unit works
- $1 buys 1,000 credits; the smallest pack is $5.
- A paid action bills the higher of its flat floor and what it actually spent on model, compute and egress — so a cheap run stays cheap.
- “Metered” means the action has no published flat floor on this page: GET /api/v1/pricing serves the live card.
- A run that never executes because the policy engine expects a score wall refunds its reserve in full. GET /api/v1/pricing serves the live rate card.
Be sure this fits
What this does not do.
Every one of these will come up in your evaluation. Here they are first, from us.
It does not get you into accounts you are not entitled to use
This is for authorized work: your accounts, your entitlements, your customers’ explicit sign-in. The `authorized:true` attestation is recorded with the run, and the acceptable-use policy is not decorative.
Some walls cannot be passed by any automation, and we say so
Score-based defences that judge the whole session are the honest end of the road. The product’s answer is a human sign-in link and a captured session — not an escalating arms race billed to you. If that is unacceptable for your target, this is the wrong tool.
Stealth is slower, gated and not the default
A full desktop profile with human-calibrated timing takes longer than a headless run, needs a Pro or Enterprise plan and an explicit attestation, and adds a per-success surcharge. Reach for it when a run is actually turned away, not pre-emptively.
Under the hood
The primitives this runs on.
Nothing here is specific to this problem — the same mechanisms carry every solution on the site.
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.
Read the mechanism — Egress, geo & localeHuman-in-the-loop handoff
A 2FA prompt, an approval push or a CAPTCHA the agent cannot clear returns status "paused" with a live session — resolve it automatically from a connected inbox, hand back a code, or drive the page yourself.
Read the mechanism — Human-in-the-loop handoffLive view & session video
POST /api/v1/live streams the browser back as Server-Sent Events while the agent works, and an opted-in run keeps a durable video you can fetch long afterwards.
Read the mechanism — Live view & session videoCredential vault
A write-only per-tenant vault: a stored secret is referenced in a goal as {{secret:NAME}}, resolved inside the browser at fill time, and redacted from every step, frame and log.
Read the mechanism — Credential vaultOver MCP, the same work is these tools
run_goalExecute a goal on a target URL you provide — observe, plan, and act until a success condition is met. Takes free text ({ url, prompt, success }) or a one-word built-in goal ({ target, goal }). Full run control: egress country and tier, humanized timing, warm-up, stealth, file upload, credentials, recording. A sign-in run parks by default on a 2FA/approval wall it can’t auto-resolve, returning { status:"paused", sessionId } (resume with submit_verification); pass hitl:false to opt out. If the result carries code:"credential_rejected", the site REFUSED the identifiers the run typed (credentialRejected.secrets names them, never their values) — running the same goal again sends the same wrong ones, so supply different credentials or send the user a connect_account link instead of retrying.
connect_accountGet a one-time link that lets a HUMAN sign into a site by hand, so Twin Browser captures the session and later runs are already logged in. Use it when a run returns code:"credential_missing", when it returns code:"credential_rejected" and you have no better credential to supply (the one stored is wrong — a retry re-types it), or when a site hard-challenges automated logins from datacenter IPs and simply cannot be signed into by an agent. Never ask the user to paste a password — send this link. Re-run the task afterwards and it restores the session (sessionRestored:true).
list_connectionsCheck whether the user finished a connect link you sent them (pending | active | connected | failed | expired) before re-running the task.
solve_captchaHand a live/paused session’s CAPTCHA to the solver and continue.
control_runDrive a PAUSED run's browser directly — click, type, press a key, scroll, or navigate. Coordinates are 0..1 fractions of the viewport, read off a screenshot. The run continues by itself once the page no longer looks blocked; there is no "done" call. For a login a human must do, prefer connect_account; for a code, submit_verification.
FAQ
When the site turns you away — common questions.
Is stealth mode on by default?
What happens when even that does not work?
Do we get charged for runs that a bot wall defeats?
What is the authorization attestation for?
Related
Other problems this layer solves.
Supplier and customer portals
Procurement, accounts-payable and supply-chain teams whose data is spread across dozens of external portals.
Competitive and market data
Pricing, product-marketing and growth teams who need the public market as structured data.
Browser infrastructure for AI products
Founders and engineering leads whose AI product has to act on the live web for every customer.
Try it on your hardest screen.
Start free, point a run at the system that is blocking you, and watch it happen live. If it does not work, the run tells you why — and what to do instead.