Clarify when to use browser pools

[dprevoznik]

summary

• create page: browsers.create() is the default while building and when configuration varies by user. Pools are for identical-attribute workloads at scale, or acquisition above the create rate limit. Removed the pool code sample and pointed to Scale for the decision. "What's next" now points to Scale instead of implying production means pools.
• scale page: the on-demand vs. pool decision now comes first, followed by what a pool gives you, sizing, and architecture patterns. Reworded the latency bullet around lowest-possible acquisition latency. Moved the Enterprise rate-limit <Info> next to the decision. Dropped the sizing paragraph that the pools page already covers.
• architecture patterns: renamed "Direct browser creation (POC)" to "On-demand creation" with when-to-use bullets that match the decision list. Removed the inaccurate claim that pools give higher concurrency. Noted that the queue pattern works with either approach. Fixed missing Worker and chromium imports in the queue example.
• plan gating: removed stale "Start-Up and Enterprise only" notes for browser pools from the pools limitations list and the pricing FAQ. The pricing table already lists pools on every plan.

validation

• git diff --check
• mint broken-links: no broken links found

🤖 Generated with Claude Code

---

Note

Low Risk
Docs-only wording and cross-links; no product code, auth, or billing logic changes.

Overview
Documentation now defaults to on-demand browsers.create() and treats browser pools as a narrow fit for identical configs at scale, rate-limit pressure, or lowest acquisition latency—not as the implied production path.

On Create, the on-demand vs pool section is rewritten, the multi-language pool sample and billing blurb are removed, an Enterprise rate-limit callout is added, and What's next points to Scale instead of the pools overview.

Scale leads with a decision checklist (on-demand vs pool), then explains pool benefits, trims redundant sizing prose, renames On-demand creation (replacing "POC"), drops the claim that pools raise concurrency, and notes queues work with either approach; the BullMQ example gains missing Worker / chromium imports.

Pools limitations and the pricing FAQ no longer say browser pools are Start-Up and Enterprise only, aligning with plan coverage elsewhere.

^{Reviewed by Cursor Bugbot for commit ff8f3d8. Bugbot is set up for automated code reviews on this repo. Configure here.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
Kernel	🟢 Ready	View Preview	Sep 28, 2026, 7:48 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[cursor]

Risk level: Very Low

Approved.

The diff is two prose sentences in introduction/create.mdx. It updates guidance on when to call browsers.create() versus using a browser pool. Code samples are unchanged. No application logic, API, auth, config, or infrastructure is touched, and code owner review is not required.

Blast radius is limited to that docs page.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Risk level: Very Low

Re-checked after the latest push. Risk is unchanged, so the existing approval stays in place.

The update still touches only prose in introduction/create.mdx (the On demand or from a pool section). It adjusts when to call browsers.create() versus a browser pool: on-demand creation for building, bursty or one-off work, and per-user configuration; pools once you are past self-serve scale with identical attributes, or when acquisition would exceed the create rate limit. Code samples are unchanged.

No application logic, API, auth, config, or infrastructure is modified. Code owner review is not required. Blast radius is that one docs page.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Risk level: Very Low

Re-checked after the latest push. Risk is unchanged, so the existing approval stays in place.

The update still touches only prose in introduction/create.mdx (the On demand or from a pool section). It drops the “occasional, bursty, or one-off workloads” phrasing for browsers.create() and adds a sentence directing Enterprise customers with rate-limit concerns to their account manager. Code samples are unchanged.

No application logic, API, auth, config, or infrastructure is modified. There is no CODEOWNERS file, so code owner review is not required. Blast radius is that one docs page.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Risk level: Very Low

Re-checked after the latest push. Risk is unchanged, so the existing approval stays in place.

The new commit only rewords one sentence in introduction/create.mdx (the On demand or from a pool section). Enterprise customers are now told to speak with their account manager about applicable rate limits and what fits their workloads. The rest of the page, including code samples, is unchanged.

The full diff against main is still two prose edits on that page. No application logic, API, auth, config, or infrastructure is modified. There is no CODEOWNERS file, so code owner review is not required. Blast radius is that one docs page.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Risk level: Very Low

Re-checked after the latest push. Risk is unchanged, so the existing approval stays in place.

The new commit only rewords prose in introduction/create.mdx (the On demand or from a pool section). It splits the Enterprise rate-limit note into an <Info> block and slightly tightens the pool recommendation. Code samples are unchanged.

The full diff against main is still that one docs page. No application logic, API, auth, config, or infrastructure is modified. There is no CODEOWNERS file, so code owner review is not required. Blast radius is that one docs page.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Risk level: Very Low

Re-checked after the latest push. Risk is unchanged, so the existing approval stays in place.

The new commit only rewords one sentence in introduction/create.mdx (the On demand or from a pool section). Pool guidance now says to consider a pool once you have built and scaled the workload and every run uses the same attributes, instead of "scaled beyond self-serve tiers." Code samples are unchanged.

The full diff against main is still that one docs page. No application logic, API, auth, config, or infrastructure is modified. There is no CODEOWNERS file, so code owner review is not required. Blast radius is that one docs page.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Risk level: Very Low

Re-checked after the latest push. Risk is unchanged, so the existing approval stays in place.

The full diff against main is prose in two docs pages:

• introduction/create.mdx — the On demand or from a pool section now treats browsers.create() as the default while building and when configuration varies per user, and recommends a pool after the workload is built and scaled with identical attributes, or when acquisition would exceed the create rate limit. An Enterprise <Info> callout was added.
• introduction/scale.mdx — the decision section is retitled, on-demand criteria are listed before pool criteria, pool benefit wording is tightened, and the same Enterprise rate-limit callout is added.

Code samples are unchanged. No application logic, API, auth, config, or infrastructure is modified. There is no CODEOWNERS file, so code owner review is not required. Blast radius is those two docs pages.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Risk level: Very Low

Re-checked after the latest push. Risk is unchanged, so the existing approval stays in place.

The full diff against main is prose in two docs pages:

• introduction/create.mdx — the On demand or from a pool section now treats browsers.create() as the default while building and when configuration varies per user, and recommends a pool after the workload is built and scaled with identical attributes, or when acquisition would exceed the create rate limit. An Enterprise <Info> callout was added.
• introduction/scale.mdx — the decision section is retitled, on-demand criteria are listed before pool criteria, pool benefit wording is tightened, and the same Enterprise rate-limit callout is added.

Code samples are unchanged. No application logic, API, auth, config, or infrastructure is modified. There is no CODEOWNERS file, so code owner review is not required. Blast radius is those two docs pages.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3c39ef1. Configure here.}

[cursor]

Risk level: Very Low

Re-checked after the latest push. Risk is unchanged, so the existing approval stays in place.

The full diff against main is documentation in four Mintlify pages:

• browsers/pools.mdx and info/pricing.mdx — drop the sentence that browser pools are limited to Start-Up and Enterprise plans.
• introduction/create.mdx — rewords when to use browsers.create() versus a pool, points readers to Scale, and removes the pool create/acquire samples from this page.
• introduction/scale.mdx — reorders the on-demand vs pool decision, retitles architecture sections, and adds Worker and chromium imports to an existing example.

No application logic, API, auth, config, or infrastructure is touched. These pages are published product docs, not model instruction files. No code owner file is present.

Blast radius is limited to those docs pages.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Risk level: Very Low

Re-checked after the merge from main. Risk is unchanged, so the existing approval stays in place.

The diff unique to this PR is documentation in four Mintlify pages:

• browsers/pools.mdx and info/pricing.mdx — drop the sentence that browser pools are limited to Start-Up and Enterprise plans.
• introduction/create.mdx — rewords when to use browsers.create() versus a pool, points readers to Scale, and removes the pool create/acquire samples from this page.
• introduction/scale.mdx — reorders the on-demand vs pool decision, retitles architecture sections, and adds Worker and chromium imports to an existing example.

The latest commit only merges main (kernel CLI skills docs already on main). No application logic, API, auth, config, or infrastructure is touched. These pages are published product docs, not model instruction files. No code owner file is present.

Blast radius is limited to those docs pages.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Risk level: Very Low

Re-checked after the latest push. Risk is unchanged, so the existing approval stays in place.

The new commits only edit two bullets in introduction/scale.mdx: the rate-limit criterion is listed earlier, and the latency example now says a heavily customized browser config. The full diff against main is still documentation in four Mintlify pages:

• browsers/pools.mdx and info/pricing.mdx — drop the sentence that browser pools are limited to Start-Up and Enterprise plans.
• introduction/create.mdx — rewords when to use browsers.create() versus a pool, points readers to Scale, and removes the pool create/acquire samples from this page.
• introduction/scale.mdx — reorders the on-demand vs pool decision, retitles architecture sections, and adds Worker and chromium imports to an existing example.

No application logic, API, auth, config, or infrastructure is touched. These pages are published product docs, not model instruction files. No code owner file is present.

Blast radius is limited to those docs pages.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Risk level: Very Low

Re-checked after the latest push. Risk is unchanged, so the existing approval stays in place.

The new commit adds one sentence in introduction/scale.mdx: default to on-demand browsers while getting started and as you scale, and treat browser pools as a fit for a specific workload. The full diff against main is still documentation in four Mintlify pages:

• browsers/pools.mdx and info/pricing.mdx — drop the sentence that browser pools are limited to Start-Up and Enterprise plans.
• introduction/create.mdx — rewords when to use browsers.create() versus a pool, points readers to Scale, and removes the pool create/acquire samples from this page.
• introduction/scale.mdx — reorders the on-demand vs pool decision, retitles architecture sections, and adds Worker and chromium imports to an existing example.

No application logic, API, auth, config, or infrastructure is touched. These pages are published product docs, not model instruction files. No code owner file is present.

Blast radius is limited to those docs pages.

  

_{Sent by Cursor Automation: Assign PR reviewers}