BoxWatch
Sign in

title: "Cron Checks API" description: "Manage cron heartbeat checks — list, create, update, delete, view ping history." last_updated: "2026-05-24"

Cron Checks API

Endpoints under /cron-checks manage cron heartbeat check definitions. For ping URL semantics (the URLs your cron job actually hits), see Public routes. Conceptual docs: Cron heartbeat monitoring.

All routes below require a bearer token.

List checks

GET/cron-checks
Auth: bearer

Returns all cron checks on your account with current status and the server hostname (if linked).

Response — 200 OK

{
  "checks": [
    {
      "id": 7,
      "user_id": 3,
      "server_id": 12,
      "server_hostname": "cron-01.prod",
      "name": "Nightly DB backup",
      "slug": "9b1a3c8e-2f4d-4a7e-9c1d-5b2e6a8d0f12",
      "interval_seconds": 86400,
      "grace_seconds": 300,
      "max_duration_seconds": 1800,
      "enabled": 1,
      "status": "up",
      "alert_on_missed": 1,
      "alert_on_fail": 1,
      "alert_on_stuck": 1,
      "alert_on_long": 0,
      "last_ping_at": "2026-05-24T03:00:14Z",
      "last_start_at": "2026-05-24T03:00:12Z",
      "last_success_at": "2026-05-24T03:00:14Z",
      "last_fail_at": null,
      "last_exit_code": null,
      "last_duration_seconds": 2,
      "created_at": "2026-04-12T11:23:00Z"
    }
  ],
  "plan_limit": 25,
  "current_count": 1,
  "plan": "pro"
}

Create check

POST/cron-checks
Auth: bearer

Request body

FieldTypeRequiredNotes
namestringyes1-100 chars.
interval_secondsintegeryesExpected interval. 60-7776000 (1 min to 90 days).
grace_secondsintegernoLateness allowance. >= 0 and <= floor(interval/2). Default 300.
max_duration_secondsinteger or nullnoStuck threshold; must be < interval_seconds.
server_idinteger or nullnoLink the check to a server. Must belong to your account.
alert_on_missedbooleannoDefault true.
alert_on_failbooleannoDefault true.
alert_on_stuckbooleannoDefault true.
alert_on_longbooleannoRequires max_duration_seconds to be set. Default false.
{
  "name": "Nightly DB backup",
  "interval_seconds": 86400,
  "grace_seconds": 600,
  "max_duration_seconds": 1800,
  "server_id": 12,
  "alert_on_long": true
}

Response — 201 Created

{
  "check": {
    "id": 7,
    "slug": "9b1a3c8e-2f4d-4a7e-9c1d-5b2e6a8d0f12",
    "name": "Nightly DB backup",
    "interval_seconds": 86400,
    "grace_seconds": 600,
    "max_duration_seconds": 1800,
    "enabled": 1,
    "status": "new"
  },
  "ping_urls": {
    "success": "https://api.boxwatch.app/ping/9b1a3c8e-2f4d-4a7e-9c1d-5b2e6a8d0f12",
    "start": "https://api.boxwatch.app/ping/9b1a3c8e-2f4d-4a7e-9c1d-5b2e6a8d0f12/start",
    "fail": "https://api.boxwatch.app/ping/9b1a3c8e-2f4d-4a7e-9c1d-5b2e6a8d0f12/fail"
  }
}

Errors

  • 400 — validation_failed with an issues array. Each issue has field and reason.
  • 402 — plan_limit_reached; body includes current, limit, plan.

Get check

GET/cron-checks/:id
Auth: bearer

Returns the check plus the last 25 pings and a total ping count.

Query parameters

ParamTypeDefaultNotes
pings_offsetinteger0Skip this many before returning 25.

Response — 200 OK

{
  "check": {
    "id": 7,
    "name": "Nightly DB backup",
    "slug": "9b1a3c8e-2f4d-4a7e-9c1d-5b2e6a8d0f12",
    "status": "up",
    "server_hostname": "cron-01.prod"
  },
  "ping_urls": {
    "success": "https://api.boxwatch.app/ping/9b1a3c8e-2f4d-4a7e-9c1d-5b2e6a8d0f12",
    "start": "https://api.boxwatch.app/ping/9b1a3c8e-2f4d-4a7e-9c1d-5b2e6a8d0f12/start",
    "fail": "https://api.boxwatch.app/ping/9b1a3c8e-2f4d-4a7e-9c1d-5b2e6a8d0f12/fail"
  },
  "pings": [
    {
      "id": 8821,
      "check_id": 7,
      "ping_type": "success",
      "exit_code": null,
      "duration_seconds": 2,
      "source_ip": "203.0.113.10",
      "user_agent": "curl/8.4.0",
      "body": null,
      "received_at": "2026-05-24T03:00:14Z"
    }
  ],
  "pings_total": 412
}

Errors

  • 404 — not_found.

Update check

PUT/cron-checks/:id
Auth: bearer

Updatable fields: name, server_id, interval_seconds, grace_seconds, max_duration_seconds, enabled, alert_on_missed, alert_on_fail, alert_on_stuck, alert_on_long. Same validation rules as create.

Response — 200 OK

{ "check": { "id": 7, "name": "Nightly DB backup", "interval_seconds": 90000 } }

Errors

  • 400 — validation_failed, or no updatable fields provided.
  • 404 — not_found.

Delete check

DELETE/cron-checks/:id
Auth: bearer

Deletes the check and its ping history.

Response — 200 OK

{ "ok": true }

Errors

  • 404 — not_found.

See also

Was this page helpful?
← Previous
Servers
Next →
Processes