docs(browser-rendering): add waitUntil guidance for JS-heavy pages (#26998)

* docs(browser-rendering): add waitUntil guidance for JS-heavy pages

- Add new partial explaining gotoOptions.waitUntil for JavaScript-heavy pages
- Add partial to all REST API endpoint docs
- Clean up timeouts reference page with dedicated waitUntil options table
- Fix default waitUntil value to domcontentloaded per API reference

* docs(browser-rendering): clarify networkidle as simplest solution, waitForSelector for advanced users

Author: kathayl

src/content/docs/browser-rendering/reference/timeouts.mdx

@@ -11,14 +11,27 @@ If any of these timers exceed their limit, the request returns a timeout error.
 
 Each timer controls a specific part of the rendering lifecycle — from page load, to selector load, to action.
 
-| Timer                                | Scope           |Default           |Max           |
-| -------------------------------------- | --------------- | --------------- | --------------- |
-|  `goToOptions.timeout`     | Time to wait for the page to load before timeout.  |   30 s       |   60 s        |
-|  `goToOptions.waitUntil`    |  Time until page load considered complete: <br />`load` = full page load, including resources, like images and stylesheets. <br />`Event.domcontentloaded` = waits until the DOM content has been fully loaded, fires before the page `load` event. <br />`Event.networkidle0` = there are no active network connections for at least 500 ms. <br />`Event.networkidle2` = there are no more than two active network connections for at least 500 ms.         |     —      |     —      |
-|  `waitForSelector`   | Time to wait for a specific element (any CSS selector) to appear on the page.  |    null      |     60 s      |
-|  `waitForTimeout`     | Additional amount of time to wait after the page has loaded to proceed with actions.  |     null     |      60 s     |
-|  `actionTimeout`     |  Time to wait for the action itself (for example: a screenshot, PDF, or scrape) to complete after the page has loaded.  |    null      |      5 min     |
-|  `PDFOptions.timeout`     |  Same as `actionTimeout`, but only applies to the [/pdf endpoint](/browser-rendering/rest-api/pdf-endpoint/). |     30 s     |     5 min      |
+| Timer                    | Scope                                                                                                              | Default | Max    |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------ | ------- | ------ |
+| `goToOptions.timeout`    | Time to wait for the page to load before timeout.                                                                  | 30 s    | 60 s   |
+| `goToOptions.waitUntil`  | Determines when page load is considered complete. Refer to [`waitUntil` options](#waituntil-options) for details.  | `domcontentloaded`  | —      |
+| `waitForSelector`        | Time to wait for a specific element (any CSS selector) to appear on the page.                                      | null    | 60 s   |
+| `waitForTimeout`         | Additional amount of time to wait after the page has loaded to proceed with actions.                               | null    | 60 s   |
+| `actionTimeout`          | Time to wait for the action itself (for example: a screenshot, PDF, or scrape) to complete after the page has loaded. | null | 5 min  |
+| `PDFOptions.timeout`     | Same as `actionTimeout`, but only applies to the [/pdf endpoint](/browser-rendering/rest-api/pdf-endpoint/).       | 30 s    | 5 min  |
+
+### `waitUntil` options
+
+The `goToOptions.waitUntil` parameter controls when the browser considers page navigation complete. This is important for JavaScript-heavy pages where content is rendered dynamically after the initial page load.
+
+| Value              | Behavior                                                                 |
+| ------------------ | ------------------------------------------------------------------------ |
+| `load`             | Waits for the `load` event, including all resources like images and stylesheets |
+| `domcontentloaded` | Waits until the DOM content has been fully loaded, which fires before the `load` event (default) |
+| `networkidle0`     | Waits until there are no network connections for at least 500 ms         |
+| `networkidle2`     | Waits until there are no more than two network connections for at least 500 ms |
+
+For pages that rely on JavaScript to render content, use `networkidle0` or `networkidle2` to ensure the page is fully rendered before extraction.
 
 ## Notes and recommendations
 You can set multiple timers — as long as one is complete, the request will fire.

src/content/docs/browser-rendering/rest-api/content-endpoint.mdx

@@ -83,6 +83,11 @@ curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-
 
 Many more options exist, like setting HTTP headers using `setExtraHTTPHeaders`, setting `cookies`, and using `gotoOptions` to control page load behaviour - check the endpoint [reference](/api/resources/browser_rendering/subresources/content/methods/create/) for all available parameters.
 
+<Render
+  file="javascript-heavy-pages"
+  product="browser-rendering"
+/>
+
 <Render
   file="setting-custom-user-agent"
   product="browser-rendering"

src/content/docs/browser-rendering/rest-api/json-endpoint.mdx

@@ -375,6 +375,8 @@ In this example, Browser Rendering first calls Anthropic's Claude Sonnet 4 model
 ]
 ```
 
+<Render file="javascript-heavy-pages" product="browser-rendering" />
+
 <Render file="setting-custom-user-agent" product="browser-rendering" />
 
 <Render file="faq" product="browser-rendering" />

src/content/docs/browser-rendering/rest-api/links-endpoint.mdx

@@ -255,6 +255,8 @@ curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-
   }'
 ```
 
+<Render file="javascript-heavy-pages" product="browser-rendering" />
+
 <Render file="setting-custom-user-agent" product="browser-rendering" />
 
 <Render file="faq" product="browser-rendering" />

src/content/docs/browser-rendering/rest-api/markdown-endpoint.mdx

@@ -116,6 +116,11 @@ curl -X 'POST' 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browse
 }
 ```
 
+<Render
+  file="javascript-heavy-pages"
+  product="browser-rendering"
+/>
+
 <Render
   file="setting-custom-user-agent"
   product="browser-rendering"

src/content/docs/browser-rendering/rest-api/pdf-endpoint.mdx

@@ -201,6 +201,11 @@ curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-
 
 If your PDF requires a font that is not pre-installed in the Browser Rendering environment, you can load custom fonts using the `addStyleTag` parameter. For instructions and examples, refer to [Use your own custom font](/browser-rendering/reference/supported-fonts/#rest-api).
 
+<Render
+  file="javascript-heavy-pages"
+  product="browser-rendering"
+/>
+
 <Render
   file="setting-custom-user-agent"
   product="browser-rendering"

src/content/docs/browser-rendering/rest-api/scrape-endpoint.mdx

@@ -126,6 +126,11 @@ Many more options exist, like setting HTTP credentials using `authenticate`, set
 Visit the [Browser Rendering API reference](/api/resources/browser_rendering/subresources/scrape/methods/create/) for all available parameters, such as setting HTTP credentials using `authenticate`, setting `cookies`, and customizing load behavior using `gotoOptions`.
 :::
 
+<Render
+  file="javascript-heavy-pages"
+  product="browser-rendering"
+/>
+
 <Render
   file="setting-custom-user-agent"
   product="browser-rendering"

src/content/docs/browser-rendering/rest-api/screenshot-endpoint.mdx

@@ -186,6 +186,11 @@ curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-
 
 Many more options exist, like setting HTTP credentials using `authenticate`, setting `cookies`, and using `gotoOptions` to control page load behaviour - check the endpoint [reference](/api/resources/browser_rendering/subresources/screenshot/methods/create/) for all available parameters.
 
+<Render
+  file="javascript-heavy-pages"
+  product="browser-rendering"
+/>
+
 <Render
   file="setting-custom-user-agent"
   product="browser-rendering"

src/content/docs/browser-rendering/rest-api/snapshot.mdx

@@ -133,6 +133,11 @@ curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-
   product="browser-rendering"
 />
 
+<Render
+  file="javascript-heavy-pages"
+  product="browser-rendering"
+/>
+
 <Render
   file="setting-custom-user-agent"
   product="browser-rendering"

src/content/partials/browser-rendering/javascript-heavy-pages.mdx

@@ -0,0 +1,16 @@
+### Handling JavaScript-heavy pages
+
+For JavaScript-heavy pages or Single Page Applications (SPAs), the default page load behavior may return empty or incomplete results. This happens because the browser considers the page loaded before JavaScript has finished rendering the content.
+
+The simplest solution is to use the `gotoOptions.waitUntil` parameter set to `networkidle0` or `networkidle2`:
+
+```json
+{
+  "url": "https://example.com",
+  "gotoOptions": {
+    "waitUntil": "networkidle0"
+  }
+}
+```
+
+For faster responses, advanced users can use `waitForSelector` to wait for a specific element instead of waiting for all network activity to stop. This requires knowing which CSS selector indicates the content you need has loaded. For more details, refer to [REST API timeouts](/browser-rendering/reference/timeouts/).