Monitors & schedules

A monitor is either a Heartbeat (your job reports to Tickingora) or an HTTP Check (Tickingora calls your endpoint). Both share the same schedule, calendar and alerting model.

{
  "type": "heartbeat",
  "name": "Bank statement import",
  "description": "MT940 import and payment matching",
  "timezone": "Europe/Warsaw",
  "schedule": { "preset": "daily", "days": [1,2,3,4,5], "start": "06:00", "end": "07:00" },
  "calendar": { "skip_holidays": true, "excluded_dates": ["2026-12-31"] },
  "notifications": { "extra_email": "finance@example.com", "on_failure": true, "on_recovery": true }
}

Unknown fields are rejected with VALIDATION_ERROR, so a typo such as "shedule" never silently falls back to a default.

Finding monitors by external_id

Pick an external_id that names the job, not the moment — production:nightly-backup, acme-shop/invoice-export. Then:

• GET /monitors?external_id=production:nightly-backup finds it;
• creating another monitor with the same external_id returns 409 MONITOR_ALREADY_EXISTS with details.monitor_id — so a set-up script or an agent can run again at any time without creating duplicates;
• PATCH can change it (or set null); deleting a monitor frees its external_id.

The id is not a secret and is shown in the dashboard. Monitors created in the dashboard have no external_id until you set one with PATCH.

Schedules

Days are ISO weekdays: 1 = Monday … 7 = Sunday. Times are HH:MM in the monitor's time zone.

Heartbeat windows are half-open [start, end): a signal at 06:59:59 counts for 06:00–07:00; a signal at exactly 07:00 belongs to the next window (if there is one). HTTP Checks are points in time and have no end.

daily — one window (or check) per selected day

{ "preset": "daily", "days": [1,2,3,4,5], "start": "06:00", "end": "07:00" }

For an HTTP Check omit end: { "preset": "daily", "days": [1,2,3,4,5], "start": "07:00" }.

A Heartbeat window may cross midnight, e.g. "start": "23:30", "end": "00:30"; it belongs to the day it starts on.

hourly — every hour between two hours

{ "preset": "hourly", "days": [1,2,3,4,5], "hour_from": 8, "hour_to": 18, "minute_start": 0, "minute_end": 15 }

Windows 08:00–08:15, 09:00–09:15 … 18:00–18:15. hour_to is the last hour that has a window. For Heartbeats, minute_end equal to minute_start means a full-hour window (08:00–09:00, 09:00–10:00, …). HTTP Checks omit minute_end.

custom — explicit times

{ "preset": "custom", "days": [1,2,3,4,5], "windows": [
  { "start": "06:00", "end": "07:00" },
  { "start": "12:00", "end": "12:30" }
] }

Up to 24 windows per day; HTTP Checks give only start for each entry.

Rules enforced on every schedule

• Windows of one monitor must not overlap.
• Free plan: at most one window or check per 60 minutes.
• Each preset accepts only its own fields; others are reported as errors.

Calendar

• skip_holidays: true skips Polish public holidays (New Year, Epiphany, Easter Sunday and Monday, 1 and 3 May, Pentecost, Corpus Christi, 15 August, 1 and 11 November, 24–26 December).
• excluded_dates adds your own days off.
• On excluded days nothing is expected and nothing alerts.

Daylight saving time

Schedules follow wall-clock time in the monitor's time zone, with deterministic rules:

• A start time that does not exist (spring forward) moves forward by the gap — 02:30 becomes 03:30.
• A start time that happens twice (fall back) uses its first occurrence.
• Window length is real time: a 60-minute window is always 60 minutes.

next_runs in every monitor response shows the next five windows (or checks) in UTC, with holidays, exclusions and DST already applied — the quickest way to confirm a schedule.

Updating with PATCH

PATCH /monitors/{id} accepts any subset of the fields above:

• top-level fields and the fields inside calendar, http, notifications and recovery replace their current values;
• schedule and arrays (such as http.headers or calendar.excluded_dates) are replaced as a whole;
• the change applies from the next window — the window in progress and all history stay as they were.

curl -sS -X PATCH https://dev.tickingora.com/api/v1/monitors/42 \
  -H "Authorization: Bearer $TICKINGORA_API_KEY" -H "Content-Type: application/json" \
  -d '{ "schedule": { "preset": "daily", "days": [1,2,3,4,5,6,7], "start": "01:30", "end": "03:00" } }'

Status

Pausing (POST /monitors/{id}/pause) removes upcoming windows and closes an open incident without a recovery e-mail. Resuming counts towards the plan's active-monitor limit. Deleting stops monitoring immediately and revokes the ping URL.

Plan limits (Free)

The same limits apply to the dashboard and the API. Exceeding one returns 403 PLAN_LIMIT_REACHED; GET /account shows current usage.