Browser check reference

The full request schema is in the auto-generated API Reference. Cheat sheet below.

Object: BrowserCheck

Field	Type	Default	Description
name	string	required	Display name; validated as a “friendly name.”
script	string	required	The Playwright script body. Wrapped in an async IIFE; max ~50KB.
frequency	enum	required	5m, 10m, 15m, 30m, or 1h.
timeout_seconds	int	60	Max script runtime, 1–300. The actual user-script budget is timeout - 30s.
check_regions	string[]	["aws-us-east-1"]	Regions to run from. Subset of supported regions. Every value currently resolves to aws-us-east-1, see the note there.
min_healthy_regions	int	1	Required healthy regions for overall status. Must be ≤ region count, and is additionally capped at runtime to the number of regions that can actually serve the check.
group_notification_ids	uuid[]	[]	Notification groups; cap of 10.
state	enum	active	active or paused. Paused checks don’t run.
tags	string[]	[]	Free-form labels for filtering and maintenance windows.
service_id	uuid | null	null	Optional logical service grouping.
current_status	enum	derived	success or failed. A legacy pending_failure value exists in the enum but nothing sets it.

Supported regions

These four values are accepted by the API:

Value	Location
aws-us-east-1	N. Virginia, USA (default)
aws-us-east-2	Ohio, USA
aws-us-west-1	N. California, USA
aws-eu-west-2	London, UK

Only aws-us-east-1 has a browser runner today

A browser check requested for any other region falls back to the US East runner, and its result is recorded against aws-us-east-1 because that is where it genuinely ran. Multiple selected regions collapse into a single run.

See regions for the full behavior, including how min_healthy_regions is capped. HTTP checks are unaffected and do run in all four.

The script API

Two globals are injected: page (Playwright Page) and step (your wrapper).

step(name, fn)

await step('Open homepage', async () => {
  await page.goto('https://example.com');
});

• name is the display label in the result UI.
• fn is an async () => Promise<void>.
• A step that throws fails. Subsequent steps are skipped.
• A screenshot is captured after every step (pass or fail).

page (Playwright Page)

The full Playwright API is available. Anything documented at https://playwright.dev/docs/api/class-page works.

Common helpers:

await page.goto(url, { waitUntil: 'networkidle' });
await page.click('text=Sign in');
await page.fill('input[name=email]', 'demo@example.com');
await page.waitForSelector('h1:has-text("Welcome")', { timeout: 10000 });
const text = await page.textContent('h1');
const ok = await page.isVisible('.success-banner');
const url = page.url();

Common assertion patterns

Browser checks don’t have a separate assertion DSL. Assertions are just JavaScript that throws.

// Wait for an element
await step('Dashboard loaded', async () => {
  await page.waitForSelector('h1:has-text("Dashboard")', { timeout: 10000 });
});

// Assert text content
await step('Welcome message correct', async () => {
  const text = await page.textContent('h1');
  if (!text?.includes('Welcome')) {
    throw new Error(`Expected "Welcome", got "${text}"`);
  }
});

// Assert URL
await step('Redirected to dashboard', async () => {
  if (!page.url().endsWith('/dashboard')) {
    throw new Error(`Expected dashboard, got ${page.url()}`);
  }
});

// Assert HTTP response
await step('Submit form', async () => {
  const [response] = await Promise.all([
    page.waitForResponse(/\/api\/login$/),
    page.click('button[type="submit"]'),
  ]);
  if (response.status() !== 200) {
    throw new Error(`Expected 200, got ${response.status()}`);
  }
});

Captured artifacts

For every result:

Artifact	Stored as	API endpoint
Step results	Inline JSON in the result row	GET /browser_check/{id}/results
Screenshots	Per-step PNGs in S3	embedded in step results
HAR file	Full network capture, S3	GET /browser_check/{id}/results/{result_id}/artifact_url
Video	1280×720 MP4 of the run, S3	same artifact_url endpoint
Web vitals	Inline JSON: {lcp_ms, fcp_ms, cls, ttfb_ms}	GET /browser_check/{id}/vitals
Console errors	Inline JSON array	embedded in result
Trace IDs	List of traceparent IDs from outgoing requests	embedded in result

The HAR and video URLs are presigned, expire in 1 hour, and are S3-direct (no proxying through SiteQwality’s API).

Endpoints

Method	Path	Purpose
POST	/browser_check	Create.
GET	/browser_check	List all.
GET	/browser_check/{id}	Detail.
PUT	/browser_check/{id}	Update (partial body).
DELETE	/browser_check/{id}	Delete.
POST	/browser_check/{id}/run	Trigger an immediate run. The response reports the regions the run actually executed in, which may differ from the check’s configured regions.
GET	/browser_check/{id}/results	List recent results.
GET	/browser_check/{id}/results/{result_id}/artifact_url	Presigned HAR + video URLs.
GET	/browser_check/{id}/vitals	Aggregated web vitals over time.

See also

• Browser check overview: concept and trade-offs.
• Quickstart: first-script walkthrough.