Check fields

A check is a single object describing what to request, how often, and what counts as healthy. Every field below can be set in YAML, in the dashboard, or through POST /v2/checks.

Required fields

Only three fields are required. Everything else has a default that suits an HTTP health endpoint.

Field	Type	Default	Notes
`name`	string	required	Unique per project. Used in alert titles.
`url`	string	required	Must be `http` or `https`.
`every`	duration	required	Minimum `10s` on Team and above, `60s` on Solo.
`expect`	integer	`200`	Exact status code match.
`timeout`	duration	`5s`	Counted as a failure, not an error.
`confirm_from`	integer	`2`	Regions that must agree before alerting.
`tags`	string[]	`[]`	Used for routing and maintenance windows.

Assertions

When a status code is not enough, add assertions. Each one is evaluated against the response; all must pass for the check to be healthy.

check with assertionsyaml

name: billing-worker
url: https://api.example.com/internal/queue
every: 30s
assert:
  - json: $.depth
    lt: 500
  - header: x-worker-version
    matches: '^2\.'
  - body: contains
    value: '"draining":false'

Assertions run on the first 64 KB

Response bodies are truncated at 64 KB before assertions are evaluated. A json assertion against a path beyond that point fails with assert_truncated.

Error codes

Failures carry a machine-readable code. These are stable and safe to branch on in a webhook consumer.

timeout — no response within timeout.
status_mismatch — responded, but not with expect.
assert_failed — status matched, an assertion did not.
tls_expired — certificate expired or not yet valid.
dns_failure — hostname did not resolve from this region.

Common questions

Why did my check alert twice?

Once for the failure and once for the recovery. Set notify_on: [failure] to suppress recovery notices.

Can two checks share a name?

Not within a project. Across projects, yes — alert titles are prefixed with the project slug.

Do maintenance windows stop the checks?

No. Checks keep running and results are recorded; only alerting is muted, so the history stays complete.

This page loads Core, Headers, Content and Utilities. No Footers module, and no custom CSS — the sidebar is a two-column .pf-grid with an inline position: sticky. More examples