---
title: "List Heartbeats"
method: GET
path: "/v1/heartbeats"
tags: ["Heartbeats"]
---

# List Heartbeats

`GET /v1/heartbeats`

## 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`
- Auth: API key in header `Authorization`

List heartbeats for the active organization, optionally filtered by a
search query and by tags: with `tag_match=all` (default) a heartbeat must
carry every tag given, with `tag_match=any` at least one. Ordered by the
given sort option (problems-first by default).

## Query parameters

- `q` string, nullable
- `sort` 'status' | 'name' | 'created_at': Ordering options for the heartbeat listing endpoint.
- `tag` string[], nullable
- `tag_match` 'all' | 'any': How a multi-tag filter combines: every tag (``ALL``) or any of them.
- `page` integer
- `size` integer

## Headers

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

## Response `200`

Successful Response

- PaginatedResponseHeartbeatRead
  - `items` HeartbeatRead[], required
    - `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
  - `total` integer, required
  - `page` integer, required
  - `size` integer, required
  - `pages` integer, 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)