[Browser Run] Document crawl event subscriptions

Author: Refaerds

src/content/changelog/browser-run/2026-09-23-crawl-event-subscriptions.mdx

@@ -0,0 +1,22 @@
+---
+title: Subscribe to Browser Run crawl events
+description: Receive crawl lifecycle events through Cloudflare Queues.
+products:
+  - browser-run
+  - queues
+date: 2026-09-23
+---
+
+import { PackageManagers } from "~/components";
+
+[Browser Run crawl jobs](/browser-run/quick-actions/crawl-endpoint/) can publish lifecycle events to [Cloudflare Queues](/queues/). Subscribe to started, updated, and finished events to track progress or trigger downstream processing without polling.
+
+To create an account-level subscription, run the following command:
+
+<PackageManagers
+	type="exec"
+	pkg="wrangler"
+	args="queues subscription create <QUEUE_NAME> --source browserRun --events crawl.started,crawl.updated,crawl.finished"
+/>
+
+For payload examples, refer to the [Browser Run event schemas](/queues/event-subscriptions/events-schemas/#browser-run).

src/content/docs/browser-run/quick-actions/crawl-endpoint.mdx

@@ -37,7 +37,7 @@ Refer to [optional parameters](/browser-run/quick-actions/crawl-endpoint/#option
 There are two steps to using the `/crawl` endpoint:
 
 1. [Initiate the crawl job](/browser-run/quick-actions/crawl-endpoint/#initiate-the-crawl-job) — A `POST` request where you initiate the crawl and receive a response with a job `id`.
-2. [Request results of the crawl job](/browser-run/quick-actions/crawl-endpoint/#request-results-of-the-crawl-job) — A `GET` request where you request the status or results of the crawl.
+2. [Request results of the crawl job](/browser-run/quick-actions/crawl-endpoint/#request-results-of-the-crawl-job) — Monitor the crawl with an event subscription or `GET` request. When it finishes, send a `GET` request for the results.
 
 Crawl jobs have a maximum run time of seven days. If a job does not finish within this time, it will be cancelled due to timeout. Job results are available for 14 days after the job completes, after which the job data is deleted.
 
@@ -85,6 +85,18 @@ The response includes a `status` field indicating the current state of the crawl
 - `errored` — The crawl job encountered an error.
 - `completed` — The crawl job finished successfully.
 
+### Subscribe to lifecycle events
+
+Use [Queues event subscriptions](/queues/event-subscriptions/events-schemas/#browser-run) as a push-based alternative to status polling. The linked reference includes setup instructions and payload schemas.
+
+Browser Run is an account-level event source. A subscription receives events for all crawl jobs in your account:
+
+- `crawl.started` — A crawl job starts.
+- `crawl.updated` — A crawled URL changes status.
+- `crawl.finished` — A crawl job finishes.
+
+These events provide lifecycle and status information, not crawled page content. After `crawl.finished`, send a `GET` request with the job ID to fetch the full results.
+
 ### Polling for completion
 
 Since crawl jobs run asynchronously, you can poll the endpoint periodically to check when the job finishes. Add `?limit=1` to the request URL so the response stays lightweight — you only need the job `status`, not the full set of crawled records.

src/content/docs/queues/event-subscriptions/events-schemas.mdx

@@ -25,6 +25,10 @@ This page provides a comprehensive reference of available event sources and thei
 
 <Render file="event-subscriptions/artifacts-events" product="queues" />
 
+### Browser Run
+
+<Render file="event-subscriptions/browser-run-events" product="queues" />
+
 ### Email Sending
 
 <Render file="event-subscriptions/email-sending-events" product="queues" />

src/content/partials/queues/event-subscriptions/browser-run-events.mdx

@@ -0,0 +1,112 @@
+import { PackageManagers } from "~/components";
+
+[Browser Run crawl](/browser-run/quick-actions/crawl-endpoint/) events are account-level. A subscription receives events for all crawl jobs in your account and does not require a source-specific selector.
+
+#### Subscribe to events
+
+##### Dashboard
+
+Follow the [subscription creation procedure](/queues/event-subscriptions/manage-event-subscriptions/#create-subscription) and select **Browser Run** as the source.
+
+##### Wrangler
+
+To subscribe with Wrangler, run the following command:
+
+<PackageManagers
+	type="exec"
+	pkg="wrangler"
+	args="queues subscription create <QUEUE_NAME> --source browserRun --events crawl.started,crawl.updated,crawl.finished"
+/>
+
+#### `crawl.started`
+
+Triggered when a crawl job starts.
+
+**Example:**
+
+```json
+{
+	"type": "cloudflare.browserRun.crawl.started",
+	"source": {},
+	"payload": {
+		"jobId": "crawl-job-1234",
+		"createdAt": "2026-09-23T14:00:00.000Z",
+		"crawlConfig": {
+			"url": "https://example.com",
+			"limit": 100,
+			"depth": 2,
+			"render": true,
+			"formats": ["markdown", "html"],
+			"source": "all"
+		}
+	},
+	"metadata": {
+		"accountId": "00000000000000000000000000000000",
+		"eventSubscriptionId": "11111111111111111111111111111111",
+		"eventSchemaVersion": 1,
+		"eventTimestamp": "2026-09-23T14:00:00.000Z"
+	}
+}
+```
+
+#### `crawl.updated`
+
+Triggered when a crawled URL changes status.
+
+**Example:**
+
+```json
+{
+	"type": "cloudflare.browserRun.crawl.updated",
+	"source": {},
+	"payload": {
+		"jobId": "crawl-job-1234",
+		"url": "https://example.com/docs/",
+		"crawlStatus": "completed",
+		"httpStatus": 200
+	},
+	"metadata": {
+		"accountId": "00000000000000000000000000000000",
+		"eventSubscriptionId": "11111111111111111111111111111111",
+		"eventSchemaVersion": 1,
+		"eventTimestamp": "2026-09-23T14:02:00.000Z"
+	}
+}
+```
+
+#### `crawl.finished`
+
+Triggered when a crawl job finishes.
+
+**Example:**
+
+```json
+{
+	"type": "cloudflare.browserRun.crawl.finished",
+	"source": {},
+	"payload": {
+		"jobId": "crawl-job-1234",
+		"jobStatus": "completed",
+		"createdAt": "2026-09-23T14:00:00.000Z",
+		"finishedAt": "2026-09-23T14:05:00.000Z",
+		"total": 3,
+		"completed": 2,
+		"errored": 1,
+		"skipped": 0,
+		"crawlConfig": {
+			"url": "https://example.com",
+			"limit": 100,
+			"depth": 2,
+			"render": true,
+			"formats": ["markdown", "html"],
+			"source": "all"
+		}
+	},
+	"metadata": {
+		"accountId": "00000000000000000000000000000000",
+		"eventSubscriptionId": "11111111111111111111111111111111",
+		"eventSchemaVersion": 1,
+		"eventTimestamp": "2026-09-23T14:05:00.000Z"
+	}
+}
+```