Heartbeats

Send heartbeat signals from your service and inspect the history of what arrived.

A heartbeat is the signal that tells Vanta your service is alive. You send one at the start of each cycle, or right after a successful piece of work, and Vanta compares its arrival to the monitor's expected interval and grace period.

Sending a heartbeat

Heartbeats are addressed by the monitor's slug, so you do not need to track its id. Authenticate with a project API key:

http
POST /v1/projects/:projectId/heartbeats/:monitorSlug
Authorization: Bearer vk_...

{
  "metadata": { "shard": "2", "queueDepth": 43 }
}

Through the Node.js SDK, the same call is:

typescript
await vanta.uptime.heartbeat('checkout-worker', {
  metadata: { shard: '2', queueDepth: 43 },
})

The metadata object is optional and attaches context to the heartbeat so you can see what the service was doing when it reported in.

Automatic heartbeats

For services that should report on a fixed cadence, vanta.uptime.start() sends heartbeats for a set of monitors on an interval:

typescript
const monitor = vanta.uptime.start('checkout-worker', {
  intervalMs: 30_000,
})

monitor.stop()

This is convenient for long-running processes that are expected to stay alive. Choose an interval comfortably inside the monitor's expected interval plus grace period so a single delayed heartbeat does not trip a false outage.

Heartbeat history

Every heartbeat is recorded. Query the history for a monitor over a time range to audit activity or to build your own visualizations:

typescript
const heartbeats = await vanta.uptime.getHeartbeats('mon_abc123', {
  from: '2026-08-20T00:00:00Z',
  to: '2026-08-27T00:00:00Z',
})

Retention and rollups

Raw heartbeats are only a short-term record. Once a heartbeat is older than the raw retention window (7 days by default), it is rolled up into an hourly aggregate and deleted. Hourly aggregates are kept for 90 days and rolled up again into daily aggregates that are kept indefinitely.

This keeps the raw table bounded no matter how many heartbeats arrive, but the history and statistics endpoints stay accurate: recent windows read raw heartbeats, older windows read the pre-aggregated rollups, and the transition never double counts a single heartbeat. Heartbeat counts and latency statistics are bucketed to the hour for windows older than raw retention.

Edge cases

  • A heartbeat that arrives during the grace period keeps the monitor up and resets the window.
  • The first heartbeat changes the monitor from unknown to up.
  • After a monitor goes down, the next heartbeat is treated as the recovery signal and resolves the open incident.
  • Sending to a slug that does not exist returns an error rather than silently creating a monitor.