HTTP check reference

The full request/response schema is in the auto-generated API Reference. This page is the human-readable cheat sheet for POST /http/job and PUT /http/job/{job_id}.

Request settings

Field	Type	Default	Description
friendly_name	string	none	Display name shown in the dashboard. 1 to 99 characters.
uri	string	required	Target URL. Must parse as an absolute URI with a host. https is required unless monitor_tls is explicitly false.
method	string	required	Any valid HTTP method token (GET, POST, HEAD, …).
run_interval_seconds	int	required	Seconds between checks. Must be at least 60 and a multiple of 60.
run_interval_thirty_seconds	bool	false	Run every 30 seconds instead. Only valid together with run_interval_seconds: 60.
timeout_ms	int	required	Per-request timeout in milliseconds. Maximum 60000.
check_regions	string[]	["aws-us-east-1"]	Locations the check runs from. Omitted or empty falls back to the default. Only the default has a runner behind it. See check regions.
min_healthy_regions	int	1	Minimum locations that must pass for the check to count as healthy. At least 1, at most the number of check_regions. Setting more than one location requires a paid plan.
confirmation_threshold	int	1	Consecutive failed checks required before the monitor transitions to failed and alerts. 1 to 10. See requiring N failed checks.
follow_redirects	bool	true	Follow HTTP redirects before evaluating the response.
request_body	string	none	Body sent with the request.
content_type	enum	none	Content-Type of the request body. See content types.
auth_type	enum	none	basic, digest, or bearer.
auth_username	string	none	Username for basic / digest auth.
auth_password	string	none	Password for basic / digest auth.
auth_bearer_token	string	none	Token for bearer auth.
success_http_codes	int[]	none	Status codes that force a success. Each must be a valid HTTP status code.
failure_http_codes	int[]	none	Status codes that force a failure. Each must be a valid HTTP status code.
custom_http_headers	map	none	Extra request headers as {name: value}.
keyword_search	string	none	Text to search for in the response body. Maximum 1000 characters; an empty string is treated as unset.
keyword_search_inverted	bool	false	Invert the assertion: fail when the keyword IS found.
keyword_search_case_sensitive	bool	false	Match case-sensitively.
keyword_search_regex	bool	false	Interpret keyword_search as a regular expression.
group_notification_ids	uuid[]	none	Notification groups to fire on state change. Maximum 10, no duplicates, must belong to your account.
monitor_tls	bool	true	Provision a paired TLS check for the URL’s hostname.
monitor_dns	bool	true	Provision a paired domain expiry check for the URL’s registrable domain. Silently skipped at create time, and rejected with 400 on update, when the host is on a shared platform suffix such as *.vercel.app.
monitor_page_speed	bool	false	Provision a paired page-speed (Lighthouse) check on a slower schedule.
tags	string[]	none	Free-form tags. Used for grouping and maintenance-window matching.
http_version	enum	auto	Preferred HTTP version for the check transport. See HTTP versions.
state	enum	active	Update only. active or paused. Paused checks stop running and alerting.
final_uri	string	none	Accepted by the API but not evaluated by the check runner today.

PUT /http/job/{job_id} takes the same fields, all optional; a request with no fields is rejected. Sending check_regions: [] on update leaves regions unchanged.

Read-only fields

Field	Type	Description
id	uuid	Check ID.
account_id	uuid	Owning account.
current_status	enum	See status enum.
last_run_at	rfc3339 | null	Most recent check execution.
last_status_change_at	rfc3339 | null	When current_status last transitioned.
created_at	rfc3339	When the check was created.
tls_job_id	uuid | null	Paired TLS check, if monitor_tls is on.
dns_job_id	uuid | null	Paired domain expiry check, if monitor_dns is on and the domain is registrable.
page_speed_job_id	uuid | null	Paired page-speed check, if monitor_page_speed is on.
group_notifications	object[] | null	Full notification-group objects resolved from group_notification_ids.
service_id	uuid | null	Service this check belongs to, set via the service endpoints.

Status enum

Status	Meaning
success	The monitor is not in a confirmed failure. A monitor whose recent checks have failed but not yet met its confirmation_threshold stays success.
failed	Confirmed failure. Notifications fire and an incident opens.
pending_failure	Legacy value. Nothing sets it today; debouncing is handled by confirmation_threshold. Treat it as success if you encounter it on an old record.

Check regions

The field validates against these four values and rejects anything else with a 400 carrying Invalid check_regions <value>. Only the first one runs checks.

Region value	Location	Runs checks today
aws-us-east-1	N. Virginia, USA	Yes. The default.
aws-us-west-1	N. California, USA	No
aws-us-east-2	Ohio, USA	No
aws-eu-west-2	London, UK	No

Setting a location with no runner does not fail loudly

Validation checks the value against the list above, not against whether anything is deployed there, so a check configured for aws-eu-west-2 is created successfully and simply never produces a result from London.

The quorum counts only locations that returned a success, and a configured location that reports nothing counts as not healthy rather than absent. So check_regions: ["aws-us-east-1", "aws-eu-west-2"] with min_healthy_regions: 2 creates a monitor that can never report healthy.

Additional check locations are on the roadmap. Until then, leave the field unset.

HTTP versions

Value	Behavior
auto	Prefer HTTP/2 via ALPN, fall back to HTTP/1.1 (default).
http1_1	Force HTTP/1.1 only. Best for some CDN / bot-management edges.
http2	Require HTTP/2; the check fails if it cannot be negotiated.
http2_with_fallback	Explicit prefer-h2-with-fallback. Same transport behavior as auto today.

The negotiated version actually observed on each run is recorded on the check result.

Content types

Value	Sent as
json	application/json
xml	application/xml
form_url_encoded	application/x-www-form-urlencoded
text	text/plain

Endpoints

Method	Path	Purpose
POST	/http/job	Create.
GET	/http/job/{job_id}	Fetch one check.
PUT	/http/job/{job_id}	Update (partial).
DELETE	/http/job/{job_id}	Delete.
GET	/http/jobs	List, with sort/filter query params.
GET	/http/tags	Distinct tags across your checks.
GET	/http/job/{job_id}/recent	Recent check runs.
GET	/http/job/{job_id}/recent-checks	Recent per-region check results.
GET	/http/job/{job_id}/events	Status-transition events.
GET	/http/job/{job_id}/uptime_percentage	Uptime percentage and incident count for a date range.
GET	/http/job/{job_id}/performance	Per-phase timing (dns/tcp/tls/ttfb/download).
GET	/http/job/result/{job_result_id}/details	Full detail for one recorded result.
GET	/http/job/result/{job_result_id}/body	Pre-signed download for a failed check’s full response body.
GET	/http/job/{job_id}/results/export	Check results as CSV (timings and outcome, no bodies).
GET	/http/job/{job_id}/page_speed	Latest page-speed result.
GET	/http/job/{job_id}/page_speed/history	Page-speed history.

Response bodies

Every check records its outcome, status code and per-phase timings. The response body is kept only when a check fails, which is when you need it to tell a 500 from a blank page from a hijacked domain. A passing check’s body is not stored.

When a check fails, the result carries:

• response_body: the first 8 KB of the response, for display.
• body_bytes: the true size of the captured body. If it is larger than response_body, the inline copy is the head of a bigger document.
• body_truncated, body_available, body_expired: whether the snippet is partial, whether the full body can be downloaded now, and whether one was captured but has aged out of your plan’s window.

Call GET /http/job/result/{job_result_id}/body for a pre-signed URL to the complete body, valid for one hour. It answers 404 when no body was captured (a passing check) and 410 when one was captured but falls outside your retention window.

A keyword assertion is evaluated against the live response while the check runs, never against the stored copy, so a keyword failure always carries the body that failed it even though the status code was 200.

How long a captured body stays readable

Plan	Failure bodies readable for
Free	5 days
Any paid plan	30 days
On request	Up to 365 days

These are read windows, not deletion schedules. The window is evaluated at the moment you ask for a body: past it, GET /http/job/result/{id}/body answers 410 and the dashboard shows the body as expired. Upgrading therefore makes older captured bodies readable again straight away, rather than only affecting new checks, and downgrading closes off older ones without deleting anything.

Do not read the table as a statement about when the stored object is destroyed. Object deletion is handled separately by the storage lifecycle on a longer schedule, and it is not the same number.

See also

• HTTP checks overview for the concept and lifecycle.
• TLS check reference for the paired certificate check.
• API Reference for wire-level shapes.