FlowynBETA
LoginSign up

Heartbeats

Expects a ping from your process. If no ping arrives within twice `interval_seconds`, Flowyn records a missed heartbeat. Three consecutive misses open an incident; the next ping closes it.

What heartbeats does

Expects a ping from your process. If no ping arrives within twice interval_seconds, Flowyn records a missed heartbeat. Three consecutive misses open an incident; the next ping closes it.

When to use heartbeats

  • Nightly cron jobs
  • Queue workers
  • Agents that run on a timetable

Authentication

Send an API key as a bearer token. Keys are shown once, belong in a server environment, and are bound to one environment: flw_test_ keys act in test and flw_live_ keys in live.

http
Authorization: Bearer flw_test_••••

Endpoint

http
POST https://api.flowyn.dev/v1/monitors

Request

Send an Idempotency-Key so a retried request cannot create a duplicate. The body is JSON.

curl -X POST https://api.flowyn.dev/v1/monitors \
  -H "Authorization: Bearer $FLOWYN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: hb-nightly-backup" \
  -d '{
    "name": "Nightly backup",
    "type": "heartbeat",
    "method": "GET",
    "url": "",
    "interval_seconds": 86400,
    "timeout_ms": 1000,
    "assertions": []
  }'

Response

Flowyn returns HTTP 201. The response is abridged here; the OpenAPI document lists every field.

Response
{
  "id": "1a6d8f2c-5b3e-4a9d-8c7f-6e0b2d4a1c95",
  "environment": "test",
  "name": "Nightly backup",
  "type": "heartbeat",
  "enabled": true,
  "paused": false,
  "current_status": "waiting",
  "interval_seconds": 86400
}

Lifecycle

  1. Create the heartbeat with type: heartbeat and an empty url.
  2. Your process calls POST /v1/monitors/{id}/ping with your API key at the end of each successful run.
  3. If no ping arrives within twice the interval, Flowyn records a missed heartbeat.
  4. Three consecutive misses open an incident; the next ping closes it.

Status values

StatusMeaning
waitingNo result yet.
healthyThe latest result passed.
degradedResults are mixed.
failingRecent results failed.
pausedNot checking.

Retries

Not applicable.

Idempotency

Pings are safe to repeat; each one is recorded as a result.

Errors

StatustypeMeaning
400invalid_requestThe body is not valid JSON, a field has the wrong type, or the body is over 1 MiB (body_too_large).
401unauthorizedMissing, malformed, or revoked API key.
402billing_errorThe monthly credit allowance is used (credit_limit_exceeded). Reads keep working.
403forbiddenThe key lacks the ability this call needs (ability_required).
404not_foundThe id does not exist in this environment.
409conflictFor example idempotency_mismatch: the Idempotency-Key was used with a different body.
422invalid_requestA field value is out of range, for example invalid_timeout.
429rate_limitedToo many requests (rate_limit_exceeded). Wait for Retry-After seconds.
5xxserver_errorFlowyn failed. The body carries an error_id to quote to support.

Limits

  • interval_seconds 30–86,400
  • A ping body may report status success, failed, or down with an optional error

Read it back

Keep the id and read the resource whenever you need its current state.

bash
curl https://api.flowyn.dev/v1/monitors/1a6d8f2c-5b3e-4a9d-8c7f-6e0b2d4a1c95/results \
  -H "Authorization: Bearer $FLOWYN_API_KEY"

Next step

Assert on response bodies with API checks.