---
title: "Update Heartbeat"
method: PATCH
path: "/v1/heartbeats/{heartbeat_id}"
tags: ["Heartbeats"]
---

# Update Heartbeat

`PATCH /v1/heartbeats/{heartbeat_id}`

## Request

- Base URL: `https://api.fettle.sh` (the document declares no server; this is the origin it was published from)
- URL: `https://api.fettle.sh/v1/heartbeats/{heartbeat_id}`
- Auth: API key in header `Authorization`

Update fields on a heartbeat.

## Path parameters

- `heartbeat_id` string, uuid, required

## Headers

- `X-Organization-Id` string, uuid, nullable

## Request body

- HeartbeatUpdate: Partial update payload — every field optional.
  - `name` string, nullable
  - `period_seconds` integer, nullable
  - `grace_seconds` integer, nullable
  - `notification_cooldown_seconds` integer, nullable
  - `channel_ids` string[], nullable
  - `tags` string[]

## Response `200`

Successful Response

- HeartbeatRead: Response model for a heartbeat, including the full ping-URL.
  - `id` string, uuid, required
  - `name` string, required
  - `state` 'PENDING' | 'UP' | 'DOWN' | 'PAUSED', required: Lifecycle state of a heartbeat. ``PENDING`` — created, never pinged; the sweep skips it (``overdue_at`` is NULL) so a freshly created heartbeat does not false-alarm. ``UP`` — pinged within ``period + grace``; the only state the sweep can flip to ``DOWN``. ``DOWN`` — a ping was missed or the job sent ``/fail``; an incident is open. ``PAUSED`` — owner-paused; inactive, never alerts.
  - `period_seconds` integer, required
  - `grace_seconds` integer, required
  - `ping_url` string, required
  - `last_ping_at` string, date-time, nullable, required
  - `last_success_at` string, date-time, nullable, required
  - `last_start_at` string, date-time, nullable, required
  - `last_duration_ms` integer, nullable, required
  - `overdue_at` string, date-time, nullable, required
  - `notification_cooldown_seconds` integer, required
  - `is_active` boolean, required
  - `channel_ids` string[]
  - `tags` string[]
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/fettle/apis/fettle-sh.md) · [All operations](https://skmtc.dev/fettle/apis/fettle-sh/llms.txt) · [OpenAPI document](https://skmtc.dev/fettle/apis/fettle-sh/revisions/f32c8a18606f?raw)