Heartbeat Monitoring
Heartbeat Monitoring is a crucial service designed to ensure the operational status of your critical systems by sending continuous requests, known as heartbeats. This proactive monitoring approach allows you to detect any potential issues or downtimes promptly, ensuring that all systems are functioning optimally and reliably. By setting up heartbeat monitors, you can receive real-time alerts and insights, helping you maintain the health of your services and quickly respond to any anomalies.
ENDPOINTS
Expand all
  • Heartbeat monitoring operations
    POST/v1/heartbeat
    DELETE/v1/heartbeat
    DELETE/v1/heartbeat/{id}
    PUT/v1/heartbeat/{id}
  • Heartbeat monitoring records
  • Heartbeat monitor statistics overview
Setup Heartbeat Monitor
This API endpoint allows you to create a new heartbeat resource.The user must provide the service_id and name for the heartbeat resource in the request body. This heartbeat will allow the monitoring of service uptime.

This endpoint helps users track the operational status of services by creating a heartbeat resource, which periodically checks the service’s status. If the service becomes unresponsive, the user will be alerted based on the heartbeat configuration.

Common use cases:

  • Service monitoring: Create a heartbeat resource to ensure that a critical service is regularly checked and downtime is quickly detected.
  • Operational health monitoring: Set up a heartbeat to receive alerts if the monitored service fails to respond at scheduled intervals.


Authorization: Bearer YOUR_TOKEN

Request Body Parameters
  • service_id string
    The unique service ID associated with the heartbeat resource.
    Example: '6766163a-568d-47b4-a1fa-91a0957e06d4'
  • name string
  • interval integer
  • enabled boolean
JavaScript
Response codes
const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/v1/heartbeat';
const data = {
  service_id: '6766163a-568d-47b4-a1fa-91a0957e06d4',
  name: 'Pinghome',
  interval: 60,
  enabled: true
};

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Delete Multiple Heartbeat Monitors
This API endpoint allows you to delete multiple heartbeat resources by providing their IDs as query parameters.

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.
Query Parameters
  • id string
    A list of heartbeat IDs to delete.
    Example: ['6766163a-568d-47b4-a1fa-91a0957e06d4', 'c03b02ec-244f-4d2c-8f68-3910071ed5c8']
JavaScript
Response codes
const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/v1/heartbeat?id=6766163a-568d-47b4-a1fa-91a0957e06d4&id=c03b02ec-244f-4d2c-8f68-3910071ed5c8';

axios.delete(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Delete Single Heartbeat Monitor
This API endpoint allows you to delete a specific heartbeat resource by providing its ID as a path parameter.

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.
Path Parameters
  • id string
    The unique ID of the heartbeat to delete.
    Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'
JavaScript
Response codes
const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/v1/heartbeat/c03b02ec-244f-4d2c-8f68-3910071ed5c8';

axios.delete(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Get Service Heartbeats
This API endpoint allows you to retrieve all heartbeats associated with a service by providing its ID in the path. It supports pagination via query parameters limit and page.

Authorization: Bearer YOUR_TOKEN

Path Parameters
  • id string
    The unique ID of the service.
    Example: 'cc7e4e8b-417d-4be0-9bde-85e353a20fa4'
Query Parameters
  • page (optional) positive integer
    The page of the result. Use this parameter to paginate through results when there are multiple pages of data.
    Example: 50.
  • limit (optional) positive integer
JavaScript
Response codes
const axios = require('axios');

const url = 'https://resource-query.api.pinghome.io/v1/service/cc7e4e8b-417d-4be0-9bde-85e353a20fa4/heartbeats?page=1&limit=50';

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Update Heartbeat Monitor
This API endpoint allows an authenticated user to update a heartbeat resource by providing its ID as a path parameter and the updated details in the request body.

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.
Path Parameters
  • id string
    The unique ID of the heartbeat to update.
    Example: '906a3444-15ce-4410-8041-89a238e9e91f'
Request Body Parameters
  • name string
    The name of the heartbeat resource.
    Example: 'My heartbeat'
  • service_id string
  • interval integer
  • enabled boolean
JavaScript
Response codes
const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/v1/heartbeat/906a3444-15ce-4410-8041-89a238e9e91f';
const data = {
  name: 'My heartbeat',
  service_id: 'cc7e4e8b-417d-4be0-9bde-85e353a20fa4',
  methods: ['GET'],
  interval: 60,
  enabled: true
};

axios.put(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Get Specific Heartbeat Information
This API endpoint allows you to retrieve heartbeat data by providing its ID.

Authorization: Bearer YOUR_TOKEN

Path Parameters
  • id string
    The unique ID of the heartbeat resource.
    Example: '445a5c1f-c0eb-403a-96d7-3976e5dc74ed'
JavaScript
Response codes
const axios = require('axios');

const url = 'https://resource-query.api.pinghome.io/v1/heartbeat/445a5c1f-c0eb-403a-96d7-3976e5dc74ed';

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
View Heartbeat Statistics
This API endpoint retrieves heartbeat statistics for a specified resource over a specified time range. Query parameters such as interval, start_date, and end_date allow controlling the time range and granularity of the statistics.

Authorization: Bearer YOUR_TOKEN


Path Parameters
  • id string
    The unique ID of the resource for which heartbeat statistics are being retrieved. Example: '47f84f9f-a742-4ef9-be40-e7d7a6fa4039'
Query Parameters
  • interval (optional) string
    Defines the interval for retrieving statistics. This can be included based on your preference.
    Accepted values: 1h, 3h, 12h, 1d, 3d, 7d, 30d
  • start_date (optional) string
  • end_date (optional) string
JavaScript
Response codes
const axios = require('axios');

const url = "https://statistic-query.api.pinghome.io/v1/heartbeat/47f84f9f-a742-4ef9-be40-e7d7a6fa4039/statistic?interval=7d&start_date=2022-04-03T21:00:00Z&end_date=2022-04-03T22:04:00Z";

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Get Heartbeat Event History
This API endpoint retrieves events related to a specified heartbeat. Query parameters such as limit and last_received_at allow controlling the number of events retrieved and filtering by the last received event time.

Authorization: Bearer YOUR_TOKEN


Path Parameters
  • id string
    The unique ID of the heartbeat for which events are being retrieved. Example: '47f84f9f-a742-4ef9-be40-e7d7a6fa4039'
Query Parameters
  • limit (optional) positive integer
    Specifies the maximum number of events to return, such as '10'. You can choose to include this parameter as needed.
  • last_received_at (optional) string
JavaScript
Response codes
const axios = require('axios');

const url = "https://statistic-query.api.pinghome.io/v1/heartbeat/47f84f9f-a742-4ef9-be40-e7d7a6fa4039/events?limit=10&last_received_at=2023-03-27T09:57:54Z";

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Submit Heartbeat Event
This API endpoint allows you to submit a heartbeat event by providing the heartbeat ID in the path.Result and message can be included in the request to submit event data.
Path Parameters
  • id string
    The ID of the heartbeat event.
Query Parameters
  • result (optional) string
    The result of the event. If not specified, it defaults to 'tick'. Other acceptable values include 'run', 'complete', and 'fail'.
    Example: 'tick'
  • message (optional) string
JavaScript
Response codes
const axios = require('axios');

const url = 'https://data-gateway.api.pinghome.io/v1/heartbeat/{id}';

axios.get(url, {
  params: {
    result: 'tick',
    message: 'Tick event sent'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).