Docs

Uptime

Create uptime checks, read their status and results, and see when your app stopped answering.

Applies to EngineCloud At launch

View as Markdown
On this page
  1. The uptime check object
  2. List uptime checks
  3. Create an uptime check
  4. Get an uptime check
  5. Update an uptime check
  6. Delete an uptime check
  7. Get an uptime check’s results

An uptime check is a request the engine makes to a URL of yours on a schedule. A check is down after two failures in a row and up again after one success. Going down and coming back each create an alert.

A self-hosted engine checks from where it runs, so it sees your app from one place. Sypnia Cloud checks from three regions and calls a check down when at least two of them fail.

The uptime check object

Fields

  • id
    string optional

    chk_….

  • name
    string optional
  • url
    URL optional
  • method
    string optional
  • interval_seconds
    integer optional
  • timeout_ms
    integer optional
  • expected_status
    string optional
  • body_contains
    string or null optional
  • headers
    object optional
  • enabled
    boolean optional
  • status
    string optional

    unknown until the first check ran. One of: up, down, paused, unknown.

  • down_since
    timestamp or null optional

    The first failure of the current outage.

  • last_checked_at
    timestamp or null optional
  • last_status_code
    integer or null optional

    The HTTP status of the latest check. null when there was no answer.

  • last_response_ms
    integer or null optional
  • last_error
    string or null optional

    Why the latest check failed: timeout, dns, connection_refused, tls, status_503, body_mismatch.

  • uptime_24h
    number or null optional

    Percent of checks that passed in the last 24 hours.

  • uptime_30d
    number or null optional
  • created_at
    timestamp optional

List uptime checks

GET /v1/uptime/checks EngineCloud

Every check of the project with its current status. This is what the MCP tool uptime returns.

Authentication
API token (read)

Query parameters

  • project
    string optional

    The project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is 403.

  • status
    string optional

    Only checks in this status. One of: up, down, paused, unknown.

  • limit
    integer, 1 to 200 optional

    Most items to return.

    Default: 50

  • cursor
    string optional

    The next_cursor of the previous page. Keep every other parameter the same.

Request

Terminal
curl "https://api.sypnia.com/v1/uptime/checks" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"

Response200

JSON
{
  "data": [
    {
      "id": "chk_1q9w3e7r5t2y",
      "name": "Shop home",
      "url": "https://shop.example.com/",
      "method": "GET",
      "interval_seconds": 60,
      "timeout_ms": 10000,
      "expected_status": "200-399",
      "body_contains": null,
      "headers": {},
      "enabled": true,
      "status": "up",
      "down_since": null,
      "last_checked_at": "2026-03-12T10:34:00Z",
      "last_status_code": 200,
      "last_response_ms": 184,
      "last_error": null,
      "uptime_24h": 100,
      "uptime_30d": 99.98,
      "created_at": "2026-02-02T09:20:00Z"
    }
  ],
  "next_cursor": null
}

Create an uptime check

POST /v1/uptime/checks EngineCloud

Starts checking a URL. The first check runs within a minute. The engine sends the header User-Agent: Sypnia-Uptime/1.0, follows up to 3 redirects and never sends cookies. Only http and https URLs on public addresses are allowed: a URL that resolves to a private or loopback address is refused, so a check cannot be used to reach inside your own network.

Authentication
API token (admin)

Query parameters

  • project
    string optional

    The project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is 403.

Headers

  • Idempotency-Key
    string, up to 255 characters optional

    A value of your own, 1 to 255 characters, that makes the call safe to repeat. See idempotency.

Body

  • name
    string, up to 80 characters optional

    A name for people. Required when creating.

  • url
    URL, up to 2,000 characters optional

    The URL to request. Required when creating.

  • method
    string optional

    The HTTP method. One of: GET, HEAD.

    Default: GET

  • interval_seconds
    integer optional

    How often to check. One of: 60, 300, 900.

    Default: 60

  • timeout_ms
    integer, 1,000 to 30,000 optional

    An answer slower than this is a failure.

    Default: 10000

  • expected_status
    string optional

    The statuses that count as up: one (200), a range (200-299) or a list (200,204,301).

    Default: 200-399

  • body_contains
    string, up to 200 characters or null optional

    Text the answer’s body must contain to count as up. Only with GET. The engine reads the first 256 KB.

  • headers
    object optional

    Up to 10 request headers. They are stored and returned as you send them, so do not put secrets here.

  • enabled
    boolean optional

    false pauses the check.

    Default: true

Request

Terminal
curl -X POST "https://api.sypnia.com/v1/uptime/checks" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Shop home", "url": "https://shop.example.com/"}'

Response201

JSON
{
  "id": "chk_1q9w3e7r5t2y",
  "name": "Shop home",
  "url": "https://shop.example.com/",
  "method": "GET",
  "interval_seconds": 60,
  "timeout_ms": 10000,
  "expected_status": "200-399",
  "body_contains": null,
  "headers": {},
  "enabled": true,
  "status": "unknown",
  "down_since": null,
  "last_checked_at": null,
  "last_status_code": null,
  "last_response_ms": null,
  "last_error": null,
  "uptime_24h": null,
  "uptime_30d": null,
  "created_at": "2026-02-02T09:20:00Z"
}

Errors

  • 400invalid_request

    The URL is not http or https, resolves to a private address, or a field is out of range. param names the field.

  • 409limit_reached

    The project already has as many checks as its plan allows (Sypnia Cloud), or as SYPNIA_QUOTA_UPTIME_CHECKS allows (engine).

Get an uptime check

GET /v1/uptime/checks/{check_id} EngineCloud

One check with its current status.

Authentication
API token (read)

Path parameters

  • check_id
    string required

    The check’s id (chk_…).

Query parameters

  • project
    string optional

    The project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is 403.

Request

Terminal
curl "https://api.sypnia.com/v1/uptime/checks/chk_1q9w3e7r5t2y" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"

Response200

JSON
{
  "id": "chk_1q9w3e7r5t2y",
  "name": "Shop home",
  "url": "https://shop.example.com/",
  "method": "GET",
  "interval_seconds": 60,
  "timeout_ms": 10000,
  "expected_status": "200-399",
  "body_contains": null,
  "headers": {},
  "enabled": true,
  "status": "up",
  "down_since": null,
  "last_checked_at": "2026-03-12T10:34:00Z",
  "last_status_code": 200,
  "last_response_ms": 184,
  "last_error": null,
  "uptime_24h": 100,
  "uptime_30d": 99.98,
  "created_at": "2026-02-02T09:20:00Z"
}

Errors

  • 404not_found

    No check has this id in the project.

Update an uptime check

PATCH /v1/uptime/checks/{check_id} EngineCloud

Changes the fields you send and leaves the rest. Set enabled to false to pause a check; a paused check has status paused and creates no alerts.

Authentication
API token (admin)

Path parameters

  • check_id
    string required

    The check’s id (chk_…).

Query parameters

  • project
    string optional

    The project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is 403.

Body

  • name
    string, up to 80 characters optional

    A name for people. Required when creating.

  • url
    URL, up to 2,000 characters optional

    The URL to request. Required when creating.

  • method
    string optional

    The HTTP method. One of: GET, HEAD.

    Default: GET

  • interval_seconds
    integer optional

    How often to check. One of: 60, 300, 900.

    Default: 60

  • timeout_ms
    integer, 1,000 to 30,000 optional

    An answer slower than this is a failure.

    Default: 10000

  • expected_status
    string optional

    The statuses that count as up: one (200), a range (200-299) or a list (200,204,301).

    Default: 200-399

  • body_contains
    string, up to 200 characters or null optional

    Text the answer’s body must contain to count as up. Only with GET. The engine reads the first 256 KB.

  • headers
    object optional

    Up to 10 request headers. They are stored and returned as you send them, so do not put secrets here.

  • enabled
    boolean optional

    false pauses the check.

    Default: true

Request

Terminal
curl -X PATCH "https://api.sypnia.com/v1/uptime/checks/chk_1q9w3e7r5t2y" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"interval_seconds": 300, "body_contains": "Add to cart"}'

Response200

JSON
{
  "id": "chk_1q9w3e7r5t2y",
  "name": "Shop home",
  "url": "https://shop.example.com/",
  "method": "GET",
  "interval_seconds": 300,
  "timeout_ms": 10000,
  "expected_status": "200-399",
  "body_contains": "Add to cart",
  "headers": {},
  "enabled": true,
  "status": "up",
  "down_since": null,
  "last_checked_at": "2026-03-12T10:33:00Z",
  "last_status_code": 200,
  "last_response_ms": 184,
  "last_error": null,
  "uptime_24h": 100,
  "uptime_30d": 99.98,
  "created_at": "2026-02-02T09:20:00Z"
}

Errors

  • 400invalid_request

    A field is out of range. param names it.

  • 404not_found

    No check has this id in the project.

Delete an uptime check

DELETE /v1/uptime/checks/{check_id} EngineCloud

Stops the check and deletes its results. Alerts it created stay.

Authentication
API token (admin)

Path parameters

  • check_id
    string required

    The check’s id (chk_…).

Query parameters

  • project
    string optional

    The project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is 403.

Request

Terminal
curl -X DELETE "https://api.sypnia.com/v1/uptime/checks/chk_1q9w3e7r5t2y" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"

Errors

  • 404not_found

    No check has this id in the project.

Get an uptime check’s results

GET /v1/uptime/checks/{check_id}/results EngineCloud

The check’s history: one bucket per hour with how many checks ran, how many failed and how long the answers took, plus the incidents, each stretch of time the check was down. Single results are kept for 7 days and hourly buckets for 400 days.

Authentication
API token (read)

Path parameters

  • check_id
    string required

    The check’s id (chk_…).

Query parameters

  • project
    string optional

    The project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is 403.

  • since
    string optional

    Start of the period.

    Default: 24h

  • until
    string optional

    End of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.

Request

Terminal
curl "https://api.sypnia.com/v1/uptime/checks/chk_1q9w3e7r5t2y/results?since=3h" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"

Response200

JSON
{
  "check_id": "chk_1q9w3e7r5t2y",
  "uptime": 99.44,
  "buckets": [
    {
      "start": "2026-03-12T08:00:00Z",
      "checks": 60,
      "failures": 0,
      "avg_ms": 181,
      "p95_ms": 240
    },
    {
      "start": "2026-03-12T09:00:00Z",
      "checks": 60,
      "failures": 1,
      "avg_ms": 190,
      "p95_ms": 262
    },
    {
      "start": "2026-03-12T10:00:00Z",
      "checks": 33,
      "failures": 0,
      "avg_ms": 184,
      "p95_ms": 251
    }
  ],
  "incidents": []
}

Errors

  • 404not_found

    No check has this id in the project.

The errors every endpoint can answer (401, 403, 429, 500, 503) are on Errors, limits, pagination.

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close