Checks

Check Model

Fields

Field

Type

Description
object
"check"
id
string
project_id
string
team_id
string
name
string
source_id
string The source that observations are written to. Nothing else is stored.
source_name
string | null
collection_slug
string The collection within the source that observations land in. Give several checks the same slug to chart them together, one strip per check under a worst-of overall row.
endpoint_url
string The HTTPS URL requested on every run.
method
headers_configured
string[] Names of the headers sent with every request. The values are stored encrypted and are never returned, so this shows what was configured without revealing the secrets.
request_body
string | null The request body sent when the method is post. Null for get.
schedule_cron
string Cron expression setting when the endpoint is requested, evaluated in UTC.
check_retry_seconds
number | null How long to wait before one confirming request settles a failed run. Null records the first result as it stands, which turns a single flake into a minute of recorded downtime.
status
The current state. A check is only ever stopped by you pausing it or by the team falling out of good standing. A failing endpoint never stops it, because the outage is the thing it is there to record.
next_fetch_at
| null When the next run is due. Null while the check is paused or disabled.
missed_slot_count
number How many scheduled slots have elapsed without a run, since the check was created or last resumed. Almost always because the project had no healthy server at the time. Missed slots are counted rather than run late: a slot describes the endpoint at one moment, so a late request would report the wrong minute. These are gaps in the uptime record, not downtime.
last_up
boolean | null Whether the most recent run found the endpoint up, meaning it answered with a 2xx. Null until the first run settles, and null again after a resume, which is what separates a check nothing has measured yet from one measured to be down.
results_hourly
CheckHourlyResults[] The last 24 hours of results, oldest first. Always 24 entries, so an hour with no runs reads as zeros rather than being absent, and a check that has never run still returns a full window. up / (up + down) over the window is the uptime for that period.
last_checked_at
| null When the endpoint was last requested, whether or not it answered. Cleared by a resume.
last_success_at
| null When the endpoint last returned a 2xx. Survives a pause, so it dates an ongoing outage.
last_failure_at
| null When the endpoint last failed to return a 2xx. Survives a pause.
consecutive_failure_count
number How many runs have failed in a row. Resets on the next success. Reporting only: the count never stops the check, however high it climbs.
last_error
string | null The error from the most recent failed run.
last_error_stage
| null Which step of the most recent failed run went wrong.
last_http_status
number | null The HTTP status returned by the most recent run. Null when nothing answered.
last_response_time_ms
number | null How long the most recent run took, in milliseconds.
created_at
updated_at

Check Test Result

Fields

Field

Type

Description
ok
boolean Whether the endpoint answered with a 2xx.
status
number The HTTP status the endpoint returned. Zero when no response was received at all.
status_text
string
response_time_ms
number How long the request took, in milliseconds.
byte_length
number How many bytes the endpoint returned.
body_preview
string The first 2 KB of the response body, for confirming you reached the endpoint you meant to.
error_stage
| null Which step went wrong. Null when the test succeeded.
error
string | null What went wrong. Null when the test succeeded.

List Checks

Endpoint

Retrieve a list of checks.

checks:read
GET
/v1/projects/:project_id/checks

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.

Query Parameters

Field

Type

Description
order_by
string Field the results are ordered by. Defaults to "created_at". Accepted values: "name","created_at".
status
string Return only checks in this state. Accepted values: "active","paused","disabled".
source_id
string Return only checks that write their observations to this source.
limit
number Maximum number of items to return. Defaults to 25. Minimum: 1. Maximum: 200.
after
string Cursor from pagination.next_cursor of a previous response. Returns the resources after that page.
before
string Cursor from pagination.prev_cursor of a previous response. Returns the resources before that page.
sort
string Sort direction for the result set. Defaults to "desc". Accepted values: "asc","desc".

Comments

  • after and before are mutually exclusive.

Response

200 
{
  message: string;
  data: Check[];
  status: 200;
  error: null;
  pagination: Pagination;
  endpoint: string;
}

Retrieve Check

Endpoint

Retrieve a single check.

checks:read
GET
/v1/projects/:project_id/checks/:check_id

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.
check_id
string Unique identifier of the check.

Response

200 
{
  message: string;
  data: Check;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Create Check

Endpoint

Create a scheduled check in a project.

checks:write
POST
/v1/projects/:project_id/checks

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.

Request Body

Field

Type

Requirement

Description
name
string
Required
Name shown for this check. Minimum length: 2. Maximum length: 128.
source_id
string
Required
Source that observations are written to. Nothing else about the response is stored. Minimum length: 1.
collection_slug
string
Required
Collection within the source that observations land in. Give several checks the same slug to chart them together, one strip per check under a worst-of overall row. Minimum length: 1. Maximum length: 64.
endpoint_url
string
Required
HTTPS URL requested on every run. Must resolve to a public address. Minimum length: 1. Maximum length: 2048.
method
string
Optional
HTTP method used to request the endpoint. Defaults to "get". Accepted values: "get","post".
headers
object | null
Optional
Headers sent with every request, for authenticating to the endpoint. Stored encrypted and never returned; responses list only the header names, as headers_configured.
request_body
string | null
Optional
Body sent with every request. Only valid when method is post, for health endpoints that answer queries over POST.
schedule_cron
string
Optional
Cron expression setting when the endpoint is requested, evaluated in UTC. Defaults to every minute, which is also the shortest supported gap. Defaults to "* * * * *". Minimum length: 1. Maximum length: 128.
check_retry_seconds
integer | null
Optional
Seconds to wait before one confirming request settles a failed run. Send null to record the first result as it stands. Defaults to 10.

Comments

  • The endpoint must be reachable over HTTPS at a public address. Addresses inside private or reserved ranges are rejected, and the check is repeated on every run, not just at create.
  • A check is created active even if the project has no servers yet. It starts running as soon as a server exists; an empty fleet delays the first run rather than changing the status.
  • The response body is never stored or parsed. Each run writes one observation recording whether the endpoint answered, its status code and how long it took.
  • A failing endpoint never stops a check, however long the failure lasts. Only pausing it, or the team falling out of good standing, stops one.
  • request_body is only accepted when method is post. Sending one with a get check is rejected rather than ignored, so a half-configured check fails at create time instead of quietly measuring the wrong request.
  • headers accepts at most 20 entries. A header whose value is null is ignored here, since on create there is nothing yet for it to remove. Names are matched case-insensitively, so two spellings of one name are stored as a single header.
  • schedule_cron must be a valid cron expression. It is evaluated in UTC, and the finest granularity is one minute.
  • collection_slug is required, and must be lowercase, start with a letter or digit, and may otherwise contain digits, letters, hyphens and underscores. Naming it here is what lets several checks deliberately share one collection and chart together; renaming the check later never moves the series, because the slug is stored rather than derived.
  • check_retry_seconds is between 1 and 20, and defaults to 10. A failed run waits this long and requests once more before it is recorded, so a single flake does not become a recorded minute of downtime. Send null to record the first result as it stands.
  • Each run writes one observation to collection_slug carrying check_id, check_name, checked_at, up, http_status, response_time_ms, error_stage, error_message and attempts. up is 1 when the endpoint returned a 2xx and 0 when it did not answer or answered with an error status, so the average of up over a period is the uptime for that period.
  • check_name is the name the check carried when the run was recorded, so a chart grouped on check_id can label its series with something readable. Renaming the check does not rewrite observations already stored.
  • checked_at is the scheduled minute rather than the moment the observation was written, so a run delayed by a confirming request still lands in the minute it describes.
  • name must be unique within the project, so a check is identifiable in a list and in the strip it charts as.

Response

201 
{
  message: string;
  data: Check;
  status: 201;
  error: null;
  pagination: null;
  endpoint: string;
}

Update Check

Endpoint

Update a check.

checks:write
POST
/v1/projects/:project_id/checks/:check_id

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.
check_id
string Unique identifier of the check.

Request Body

Field

Type

Requirement

Description
name
string
Optional
Name shown for this check. Minimum length: 2. Maximum length: 128.
collection_slug
string | null
Optional
Collection within the source that observations land in. Give several checks the same slug to chart them together, one strip per check under a worst-of overall row.
endpoint_url
string
Optional
HTTPS URL requested on every run. Must resolve to a public address. Minimum length: 1. Maximum length: 2048.
method
string
Optional
HTTP method used to request the endpoint. Accepted values: "get","post".
headers
object | null
Optional
Headers sent with every request, for authenticating to the endpoint. Stored encrypted and never returned; responses list only the header names, as headers_configured.
request_body
string | null
Optional
Body sent with every request. Only valid when method is post, for health endpoints that answer queries over POST.
schedule_cron
string
Optional
Cron expression setting when the endpoint is requested, evaluated in UTC. Defaults to every minute, which is also the shortest supported gap. Minimum length: 1. Maximum length: 128.
check_retry_seconds
integer | null
Optional
Seconds to wait before one confirming request settles a failed run. Send null to record the first result as it stands.

Comments

  • Changes take effect on the next run; a run already in flight finishes under the old configuration.
  • A changed schedule_cron takes effect from the next run onward.
  • At least one field must be provided.
  • Any field not listed here is rejected, including source_id, which cannot be changed after create. Create a new check to record into a different source.
  • Clearing request_body is required before changing method from post to get; a check cannot keep a body it would never send.
  • headers is a patch, not a replacement, because the values are write-only and never returned. A name mapped to a string adds or replaces that header, a name mapped to null removes it, and a name you do not mention keeps its stored value. Omit the field to leave every header alone, or send null in place of the object to remove all of them.
  • headers names are matched case-insensitively, so patching authorization replaces a stored Authorization rather than adding a second header. The spelling you send is the one stored and sent.
  • headers accepts at most 20 entries, counted after the patch is applied.
  • schedule_cron must be a valid cron expression, evaluated in UTC. Changing it restarts the missed-slot count from the edit, since slots before it belonged to a different schedule.
  • Send check_retry_seconds as null to stop confirming failures and record the first result as it stands.
  • Changing collection_slug starts a new series. Observations already written stay where they are, so a chart over the old collection stops at the edit.

Response

200 
{
  message: string;
  data: Check;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Delete Check

Endpoint

Delete a check.

checks:delete
DELETE
/v1/projects/:project_id/checks/:check_id

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.
check_id
string Unique identifier of the check.

Comments

  • Observations the check already wrote are not deleted. They belong to the source and stay queryable, so a chart of past uptime keeps working.

Response

200 
{
  message: string;
  data: null;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Pause Check

Endpoint

Pause a check so it stops running.

checks:write
POST
/v1/projects/:project_id/checks/:check_id/pause

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.
check_id
string Unique identifier of the check.

Comments

  • Only an active check can be paused. Pausing an already-paused check succeeds and changes nothing.
  • A pause is a gap in the uptime record rather than downtime. Nothing is recorded for the minutes it covers.

Response

200 
{
  message: string;
  data: Check;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Resume Check

Endpoint

Resume a paused check.

checks:write
POST
/v1/projects/:project_id/checks/:check_id/resume

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.
check_id
string Unique identifier of the check.

Comments

  • Resumes a check you paused. The failure count starts again from zero.
  • A check the system stopped while the team was not in good standing is not resumable here and returns 400. It starts again on its own once the team is back in good standing.

Response

200 
{
  message: string;
  data: Check;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Test Check

Endpoint

Request the endpoint once without recording anything.

checks:write
POST
/v1/projects/:project_id/checks/:check_id/test

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.
check_id
string Unique identifier of the check.

Comments

  • Nothing is recorded and no health field or schedule is changed, so this is safe to run against a live check. The result does not appear in the uptime history.
  • The response reports the HTTP status, how long the request took, and the first 2 KB of the body so you can confirm you reached the endpoint you meant to.
  • There is no confirming retry here, unlike a scheduled run: a test reports what happened rather than settling a verdict.

Response

200 
{
  message: string;
  data: CheckTestResult;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Referenced Types

ISODateString

An ISO 8601 date-time string returned at the JSON API boundary.

CheckMethod

get
post

Stored as plain strings rather than Postgres enums: nothing queries by either, so a database enum would only buy DDL on every added value. CheckStatus stays an enum because it IS queried, and backs the dispatch index.

CheckStatus

active
paused
disabled

CheckErrorStage

request
response