Heartbeats

Create a heartbeat

Create a heartbeat to monitor a cron job or periodic task. A unique ping token is generated for you.

POSThttps://api.vantaj.co/v1/heartbeats

Requires an API key with the heartbeats:write scope.

Authorizations

Authorizationstringheaderrequired

Bearer authentication using your API key: Authorization: Bearer <token>

Body

application/json

project_idstring<uuid>required

Project the heartbeat belongs to.

namestringrequired

Display name (1–200 characters).

interval_secondsinteger

Expected ping interval.

Allowed:6030090018003600216004320086400Default:3600

grace_secondsinteger

Grace period before a missed ping triggers an incident.

Allowed:6030090018003600Default:300

schedule_typestring

Whether the schedule is a fixed interval or a cron expression.

Allowed:intervalcronDefault:interval

cron_expressionstring | null

Cron schedule. Required when schedule_type is 'cron'.

timezonestring

IANA time zone for cron scheduling.

Default:UTC

Create a heartbeat

cURL

curl --request POST \
  --url 'https://api.vantaj.co/v1/heartbeats' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "project_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "name": "Nightly backup",
  "interval_seconds": 86400,
  "grace_seconds": 300
}'

{
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "name": "Nightly backup",
    "token": "hb_3f8a1c2e9d",
    "status": "up",
    "schedule_type": "interval",
    "interval_seconds": 86400,
    "grace_seconds": 300,
    "cron_expression": null,
    "timezone": "UTC",
    "last_pinged_at": "2026-06-21T02:00:00Z",
    "project_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "created_at": "2026-01-15T10:30:00Z"
  }
}