Heartbeat Monitoring

Create a new heartbeat monitoring resource by providing the required service_id and name in the request body. This resource acts as a check-in point for recurring jobs or processes that are expected to send heartbeat signals at defined intervals.

Once the heartbeat is created, your system or job must send regular requests (pings) to the assigned endpoint. If a ping is missed beyond the expected interval, the monitor will be marked as unhealthy, and an alert can be triggered based on your configuration.

Use cases:

• Background job monitoring — Ensure cron jobs, queue workers, or scheduled scripts are executing on time.
• System health visibility — Detect stalled or silently failed processes before they cause downstream issues.
• Proactive alerting — Receive notifications when heartbeat pings stop, signaling a potential failure or delay.

To send check-ins, use the unique heartbeat endpoint returned in the creation response.

Authorization: Bearer YOUR_TOKEN

Delete multiple heartbeat monitoring resources in a single request by passing their heartbeat_ids as query parameters. This bulk operation is useful when cleaning up unused, test, or deprecated heartbeat monitors from your monitoring system.

It helps keep your workspace organized and ensures that only actively used heartbeats are retained.

Use cases:

• Batch cleanup — Remove several outdated or inactive heartbeat monitors at once to reduce clutter.
• Decommissioning — Clean up heartbeat resources related to retired services or jobs.
• Environment reset — Reset monitoring state between staging, production, or test environments.

To retrieve a list of active heartbeat monitors before deletion, use the Get Heartbeats List endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

• On success, the specified heartbeats will be deleted, and a confirmation message along with the IDs of the deleted heartbeats will be returned.
• If the request is unauthorized or the provided IDs are invalid, an error message will be returned, specifying the issue.

Delete a specific heartbeat monitoring resource by providing its heartbeat_id as a path parameter. Once deleted, the associated check-in URL becomes inactive, and no further heartbeat pings will be accepted for that resource.

This operation is useful when decommissioning a job, script, or service that no longer needs monitoring.

Use cases:

• Service retirement — Cleanly remove monitoring for a job or service that has been shut down.
• Test cleanup — Delete temporary heartbeat resources created during development or staging.
• Resource hygiene — Keep your monitoring environment lean by removing obsolete entries.

To view heartbeat monitor before deletion, use the Get Heartbeats Information endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

• On success, the specified heartbeat will be deleted, and a confirmation message will be returned.
• If the request is invalid or contains invalid parameters, an error message will indicate the issue.

Retrieve all heartbeat monitoring resources associated with a specific service by providing the service_id in the path. This endpoint returns a paginated list of heartbeats, helping you understand which recurring jobs, scripts, or processes are currently being tracked under that service.

Use query parameters such as limit and page to control pagination and manage large sets of heartbeat monitors efficiently.

Use cases:

• Service-level visibility — See all heartbeats linked to a given service for monitoring coverage review.
• Bulk operations — Use the results to prepare for updates or deletions of multiple heartbeat monitors.
• Audit readiness — Verify that all critical background tasks within a service have monitoring in place.

To inspect a specific heartbeat’s details, use the Get Single Heartbeat Monitor endpoint.

Authorization: Bearer YOUR_TOKEN

Update the configuration of an existing heartbeat monitor by providing its heartbeat_id in the path and submitting the updated values in the request body. You can modify fields such as the name or the interval that determines when a missed heartbeat should be treated as a failure.

This operation helps ensure that heartbeat monitors stay aligned with the expected behavior of the processes or systems they track.

Use cases:

• Rename jobs — Update the name of the heartbeat resource to reflect a new job title or function.
• Change incident trigger interval — Update the interval that defines how long the system waits before flagging a missed heartbeat as an incident.
• Reorganize services — Move a heartbeat to a different service context if team responsibilities or architecture shift.

To review a heartbeat's current configuration before updating, use the Get Single Heartbeat Monitor endpoint.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

• On success, the heartbeat resource will be updated, and a confirmation message will be returned.
• If the request is invalid or cannot be processed, an error message will indicate the issue, such as an invalid URL; if the heartbeat resource is not found, an error will specify that the heartbeat does not exist.

Retrieve detailed information about a specific heartbeat monitor by providing its heartbeat_id in the path. The response includes key details such as the monitor’s name, associated service, interval setting.

This endpoint is useful for reviewing how a heartbeat is configured before updating it or troubleshooting missed signals.

Use cases:

• Configuration review — Check the current settings of a heartbeat monitor before making updates or deletions.
• Audit and visibility — View how a particular job or task is being tracked through heartbeat monitoring.
• Troubleshooting — Inspect the interval and metadata to understand why a heartbeat might be flagged as missed.

To make updates to a heartbeat, use the Update Heartbeat Monitor endpoint.

Authorization: Bearer YOUR_TOKEN

Retrieve time-based execution statistics for a specific heartbeat monitor by providing its heartbeat_id in the path. Use query parameters such as start_date, end_date, and interval to define the time range and level of detail for the data.

The response includes a list of records showing heartbeat activity over time. Each record may contain values such as:

• tick_count — Number of expected heartbeat intervals during that period.
• run_count — Number of actual check-ins (pings) received.
• fail_count — Number of intervals that were missed and counted as failures.
• complete_count — Number of successful intervals (with timely pings).
• received_at — Timestamp of the recorded data point.

Use cases:

• Heartbeat reliability tracking — Identify how consistently a job or service sends heartbeat pings.
• Failure pattern detection — Analyze missed or delayed check-ins across time intervals.
• Monitoring dashboards — Feed data into charts for visualizing heartbeat health over time.

Authorization: Bearer YOUR_TOKEN

Retrieve the full event history for a specific heartbeat monitor by providing its heartbeat_id in the path. This endpoint returns a list of recorded heartbeat events, allowing you to track when check-ins were received and whether they were successful or missed.

You can use query parameters like limit to control the number of results and last_received_at to fetch events after a specific timestamp, which is useful for pagination or incremental analysis.

Use cases:

• Incident analysis — Review missed heartbeats and their timestamps to understand when a job failed to report in.
• System auditing — Verify whether jobs or scripts checked in during critical time windows.
• Monitoring history — Build a timeline of all heartbeat events for visualization or reporting.

Authorization: Bearer YOUR_TOKEN

Submit a heartbeat check-in to signal that a scheduled job or background task has run successfully. To record a new event, provide the heartbeat_id in the path. You can also include an optional result (e.g., success, fail) and a custom message in the request body to describe the event outcome.

Each check-in helps verify that your monitored service is operational and reporting on schedule. If check-ins are not received within the configured interval, the system will automatically mark the heartbeat as failed.

Use cases:

• Automated job reporting — Ping this endpoint from cron jobs, queue workers, or scripts to indicate successful execution.
• Failure tracking — Send a fail result to indicate that a job ran but encountered an issue.
• Operational logging — Include meaningful messages with each event to support debugging and job history reviews.