> ## Documentation Index
> Fetch the complete documentation index at: https://docs.larm.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Heartbeat

> Monitor cron jobs, scheduled tasks, and background workers

<ParamField path="token" type="string" required>
  Heartbeat monitor token, found in monitor settings
</ParamField>

Heartbeat monitors work by expecting a periodic ping. If the ping stops arriving within the configured interval, Larm marks the monitor as down and fires alerts.

## Endpoint

```
ANY https://app.larm.dev/api/heartbeat/{token}
```

Accepts any HTTP method (GET, POST, HEAD, etc.). The token is found in your heartbeat monitor's settings in the dashboard.

<Note>
  No `Authorization` header is needed. The token in the URL is the authentication.
</Note>

## Response

Every call returns `200 {"status": "ok"}`. This is deliberate — invalid tokens, missing monitors, and rate-limited pings all return the same response to prevent token enumeration.

<ResponseExample>
  ```json 200 theme={null}
  {
    "status": "ok"
  }
  ```
</ResponseExample>

## Rate limiting

To bound storage from abusive ping rates, Larm records at most one heartbeat per token within a window of `interval_seconds × 100` milliseconds — roughly 10 pings per expected interval. Pings beyond that within the same window still return `200 {"status": "ok"}` but are not stored. Extra pings never cause an alert.

## Examples

### Cron job

Ping after your job completes. If the job fails or hangs, the ping never arrives and Larm alerts you.

```bash theme={null}
# Add to the end of your crontab entry
0 * * * * /usr/local/bin/backup.sh && curl -sf https://app.larm.dev/api/heartbeat/YOUR_TOKEN
```

### curl

```bash theme={null}
curl https://app.larm.dev/api/heartbeat/YOUR_TOKEN
```

### Python

```python theme={null}
import requests

requests.get("https://app.larm.dev/api/heartbeat/YOUR_TOKEN")
```

### Node.js

```javascript theme={null}
fetch("https://app.larm.dev/api/heartbeat/YOUR_TOKEN");
```

### Ruby

```ruby theme={null}
require "net/http"

Net::HTTP.get(URI("https://app.larm.dev/api/heartbeat/YOUR_TOKEN"))
```