A status page backed by real monitors

By the end of this guide, you have a public status page defined in code, with components named the way your users talk about your product, and automation rules that open and resolve incidents from the checks that test each component.

Public Checkly status page Danube Shop Status reporting 2 services experiencing issues, with an open Catalog API outage incident in Investigating state, the Catalog API component in major outage, and the Storefront component in degraded performance

To follow along without your own app, clone the sample project. It monitors the search flow and the books API of the Danube demo shop.

Let your agent do it

To run this guide from your terminal or your coding agent, run npx checkly init in your project first. It installs the Checkly CLI and Checkly Skills for your agent. Then paste the prompt below into Claude Code, Cursor, Codex, or any agent that supports skills. It builds the same setup as this guide, proves it with npx checkly test --record, and stops for your confirmation before npx checkly deploy.

Prompt

Set up a public Checkly status page for this project, driven by the checks that test each user-facing feature.

Success criteria:
1. Ask me which features my users depend on. Model each as a `StatusPageV3Component` on one `StatusPageV3`, grouped under a `GROUP` component, named the way users talk about them.
2. Make sure each component has a check that proves it works: a Playwright Check Suite or Browser Check for browser flows, an API check for public APIs. Give each check a tag only its component uses, such as `status-storefront`.
3. Add a `StatusPageV3AutomationRule` per tag that sets the component to `MAJOR_OUTAGE`, with a first and last update written for customers. When one feature depends on another, list the dependent component too with a lower impact.
4. Set a project-wide retry strategy, so a single failed request never opens a public incident.
5. Run `npx checkly test --record` and show me the session link.
6. Show me `npx checkly deploy --preview` and wait for my confirmation before deploying. Then give me the public status page URL.

Explain each file you changed and why.

The steps below are what the agent does, in the open.

Step 1: Tag the checks that prove each feature works

A status page is only as honest as what drives it. Drive each component with a check that does what a user does: search for a book, call the API, and assert on the answer. The tag on each check is the contract between the check and the status page. Use one tag per component, and do not reuse it for anything else. The storefront component is backed by a search flow. Run it as a Playwright Check Suite or a Browser Check. Both use the same test file:

import { defineConfig } from 'checkly'
import { Frequency, RetryStrategyBuilder } from 'checkly/constructs'

export default defineConfig({
  projectName: 'Docs guide: A status page backed by real monitors',
  logicalId: 'docs-guide-communicate-availability',
  repoUrl: 'https://github.com/checkly/docs',
  checks: {
    frequency: Frequency.EVERY_5M,
    locations: ['us-east-1', 'eu-west-1'],
    // A public incident needs a confirmed failure, not a blip.
    retryStrategy: RetryStrategyBuilder.fixedStrategy({
      baseBackoffSeconds: 30,
      maxRetries: 2,
      sameRegion: true,
    }),
    checkMatch: '**/checks/**/*.check.ts',
    playwrightConfigPath: './playwright.config.ts',
    playwrightChecks: [
      {
        name: 'Storefront search',
        logicalId: 'storefront-search',
        frequency: Frequency.EVERY_10M,
        locations: ['us-east-1', 'eu-west-1'],
        // The tag is what connects this check to the Storefront component.
        tags: ['status-storefront'],
      },
    ],
  },
  cli: {
    runLocation: 'us-east-1',
  },
})

import { BrowserCheck, Frequency } from 'checkly/constructs'
import * as path from 'path'

new BrowserCheck('storefront-search-browser', {
  name: 'Storefront search (Browser Check)',
  frequency: Frequency.EVERY_10M,
  // The tag is what connects this check to the Storefront component.
  tags: ['status-storefront'],
  code: {
    entrypoint: path.join(__dirname, '../tests/search.spec.ts'),
  },
})

tests/search.spec.ts

import { test, expect } from '@playwright/test'

test('a shopper can search for a book', async ({ page }) => {
  await page.goto('https://danube-web.shop/')

  await page.locator('input[name="searchbar"]').fill('haben')
  await page.getByRole('button', { name: 'Search' }).click()

  await expect(page.locator('.preview').first()).toContainText('Haben oder haben')
})

The retry strategy in the config matters more here than anywhere else. An alert that fires on a blip wakes one person. An incident that opens on a blip tells every customer your shop is down. Each failed run is retried twice in the same region before it counts. The Catalog API component is backed by an API check on the endpoint the storefront reads from:

checks/books-api.check.ts

import { ApiCheck, AssertionBuilder } from 'checkly/constructs'

new ApiCheck('catalog-api-books', {
  name: 'Catalog API: list books',
  // The tag is what connects this check to the Catalog API component.
  tags: ['status-catalog-api'],
  degradedResponseTime: 1000,
  maxResponseTime: 5000,
  request: {
    method: 'GET',
    url: 'https://danube-web.shop/api/books',
    assertions: [
      AssertionBuilder.statusCode().equals(200),
      AssertionBuilder.jsonBody('$.length').greaterThan(0),
    ],
  },
})

Step 2: Describe the page in code

A status page is built from components. A component is either a service with its own status and 90-day uptime, or a group that nests services under one heading and shows their average uptime. Name components after what users do, not after your architecture. Your users search for books. They do not care which pod serves the search.

checks/status-page.check.ts

import {
  StatusPageV3,
  StatusPageV3AutomationRule,
  StatusPageV3Component,
} from 'checkly/constructs'

export const statusPage = new StatusPageV3('danube-status', {
  name: 'Danube Shop Status',
  url: 'danube-shop-status',
  description: 'Live status of the Danube web shop, measured by synthetic monitors.',
  defaultTheme: 'AUTO',
})

// Components are named the way your users talk about the product.
const shop = new StatusPageV3Component('shop-group', {
  statusPage,
  type: 'GROUP',
  name: 'Danube shop',
  displayOrder: 0,
})

const storefront = new StatusPageV3Component('storefront', {
  statusPage,
  name: 'Storefront',
  description: 'Browsing and searching for books',
  parent: shop,
  displayOrder: 1,
})

const catalogApi = new StatusPageV3Component('catalog-api', {
  statusPage,
  name: 'Catalog API',
  description: 'The public books API',
  parent: shop,
  displayOrder: 2,
})

url becomes the subdomain, so this page is served at danube-shop-status.checkly-status-page.com. It must be unique across all Checkly accounts, so pick your own. Add customDomain when you are ready to serve it from status.yourdomain.com; see custom domains.

Step 3: Open incidents from failing checks

An automation rule connects tags to components. When a check with one of the rule’s tags fails, Checkly opens one incident with the rule’s first update and sets each listed component to its impact. When the check recovers, Checkly posts the last update and resolves the incident. Add the rules to the same file:

checks/status-page.check.ts

// When a check tagged status-storefront fails, the storefront is down.
new StatusPageV3AutomationRule('storefront-outage', {
  statusPage,
  name: 'Storefront outage',
  tags: ['status-storefront'],
  firstUpdate: 'Searching for books is failing. We are investigating.',
  lastUpdate: 'Search is working again.',
  components: [{ component: storefront, targetImpact: 'MAJOR_OUTAGE' }],
})

// The storefront reads from the API, so an API failure degrades it too.
new StatusPageV3AutomationRule('catalog-api-outage', {
  statusPage,
  name: 'Catalog API outage',
  tags: ['status-catalog-api'],
  firstUpdate: 'The Catalog API is returning errors. Book listings may be incomplete. We are investigating.',
  lastUpdate: 'The Catalog API has recovered.',
  components: [
    { component: catalogApi, targetImpact: 'MAJOR_OUTAGE' },
    { component: storefront, targetImpact: 'DEGRADED_PERFORMANCE' },
  ],
})

The second rule is where a status page earns trust. The Danube storefront loads its book list from /api/books, so when the API fails, shoppers see it in the storefront before any storefront check fails. The rule says so on the page. Degraded performance does not lower the storefront’s uptime; only partial and major outages do. See uptime calculation. Write firstUpdate and lastUpdate for customers, not for your on-call. They are posted to the public page and emailed to subscribers, because notifySubscribers defaults to true.

Incident automation is available on Team and Enterprise plans. View pricing

Test the checks, then preview what the deploy creates:

Terminal

npx checkly test --record

Terminal

Running 3 checks in us-east-1.

checks/books-api.check.ts
  ✔ Catalog API: list books (14ms)
checks/search.check.ts
  ✔ Storefront search (Browser Check) (3s)
playwright.config.ts
  ✔ Storefront search (5s)

3 passed, 3 total

Terminal

npx checkly deploy --preview

Terminal

Create:
    ApiCheck: catalog-api-books
    PlaywrightCheck: storefront-search
    BrowserCheck: storefront-search-browser
    StatusPageV3: danube-status
    StatusPageV3AutomationRule: catalog-api-outage
    StatusPageV3AutomationRule: storefront-outage
    StatusPageV3Component: catalog-api
    StatusPageV3Component: shop-group
    StatusPageV3Component: storefront

Terminal

npx checkly deploy

Open https://<your-url>.checkly-status-page.com. Every component is operational.

Verify it works

Break the API check on purpose. In checks/books-api.check.ts, change statusCode().equals(200) to statusCode().equals(201) and run npx checkly deploy. When the sample was deployed that way, the first run failed, was retried twice 30 seconds apart, and the incident opened about a minute after the deploy. The page in the screenshot at the top of this guide is what customers saw: Catalog API in major outage, Storefront degraded, and the first update from the rule. Now read it from your coding agent through the Checkly MCP server:

Prompt

Using Checkly, show me the open incidents on the Danube Shop Status page. For each one, list the affected components and their impact, find the failing checks that carry the matching status tag, and summarize their latest result.

The agent lists the open incident with its components, finds Catalog API: list books failing under the status-catalog-api tag, and reports that the API answered 200 OK while one of two assertions failed, after three attempts from N. Virginia. That is enough to tell a broken check from a broken API before you say anything more in public. Once you know the cause, post it from the same session:

Prompt

Post an Identified update to that incident: "We found the cause: a bad deploy of the Catalog API. A fix is rolling out." Do not notify subscribers.

The update goes straight to the public page, so read what your agent drafted before you let it post. Change the assertion back to equals(200) and deploy again. The next passing run resolves the incident with the rule’s last update, and the incident page keeps the full timeline:

Public incident page for Catalog API outage, lasted 1 minute, with Catalog API in major outage and Storefront in degraded performance on the component timeline, and three updates: Investigating from the automation rule, Identified posted through the MCP server, and Resolved from the automation rule

Diagnose failures with traces: your status page now tells users that something is broken. Find out why, from the failed check’s screenshots and Playwright trace.

Getting Started

Detect

Communicate

Resolve

Examples

A status page backed by real monitors

Step 1: Tag the checks that prove each feature works

Step 2: Describe the page in code

Step 3: Open incidents from failing checks

Verify it works

Next

Reference

​Step 1: Tag the checks that prove each feature works

​Step 2: Describe the page in code

​Step 3: Open incidents from failing checks

​Verify it works

​Next

​Reference

Step 1: Tag the checks that prove each feature works

Step 2: Describe the page in code

Step 3: Open incidents from failing checks

Verify it works

Next

Reference