Which model should I use?
- GPT-6 Luna (
gpt-6-luna, recommended) with High reasoning is the V4 default and the low-cost pick for simple and high-volume tasks. OmitmodelandmodelParamsto use it; Bedrock-only projects retain their compatible default. - GPT-6.1 Sol (
gpt-6.1-sol) — harder reasoning. - Claude Opus 5 (
claude-opus-5) — the hardest work.
How do I get the live browser URL?
A V4 run’sbrowser.ready event (new browser) or browser.reattached event (follow-up reusing the open browser) contains live_view_url. Embed it in an iframe or open it in a browser.
Getting blocked by a website
Stealth and proxies are active by default. If you’re still getting blocked:- Use a profile with logged-in cookies to bypass login walls.
- Try a different proxy country to match the target region.
Rate limited (429 errors)
HTTP request limits, browser concurrency, and a full session message queue can all return 429. Inspect the response before retrying: increasing browser concurrency does not increase the general request bucket used by V4 event reads. Use bounded workers, stagger polling, and respectRetry-After when provided. The SDK retries 429 responses, but a sustained workload needs its own request budget. See Concurrency and limits for account-limit lookup, polling budgets, queue behavior, and error handling.
For insufficient-balance or API-key spending-cap errors (402), see Billing and credits.
How do I get a V4 judge verdict?
Passjudge: {} when creating a run to ask an LLM to evaluate its completed
trajectory. Add context with your evaluation criteria when needed. Judging
is opt-in, and the judge’s LLM call is billed to the run. Omit judge to keep
the default behavior without that extra call.
The verdict arrives after the run becomes terminal. wait_for_completion() /
waitForCompletion() waits for the run, so its returned judgement can still
be null. Refresh that same run’s summary to retrieve the verdict:
judgement is still null, it is unavailable, not a pass or fail.
It may remain unavailable; do not poll forever. You can fetch the same run
again later without creating another run. A completed run status alone is
not a judge verdict.
See the create-run reference for judge and
the run summary for judgement.
Which API version should I use?
Use V4 for difficult tasks where accuracy matters. It supports:- Run-focused API with a cheap status polling endpoint
- Conversation sessions with follow-ups
- Persistent workspaces and turn-scoped file attachments
- Incremental events for custom UIs and monitoring
- Per-session cost breakdown (LLM, search, browser, proxy), run cost caps, and optional judgement