Référence de l’API Moniteurs

Valeurs possibles des champs

Emplacement du moniteur

ValeurDescription
US_EAST_1Virginie du Nord
CA_CENTRAL_1Canada (Montréal)
EU_CENTRAL_1Francfort
AP_NORTHEAST_1Tokyo

Types d’alerte de moniteur

ValeurDescription
INCIDENTAlerte d’incident
EMAILAlerte par e-mail
SMSAlerte SMS
SLACKAlerte Slack
DISCORDAlerte Discord
MICROSOFT_TEAMSAlerte Microsoft Teams
PHONE_CALLAlerte par appel téléphonique
WEBHOOKAlerte webhook
GOOGLE_CHATAlerte Google Chat
WHATSAPPAlerte WhatsApp

Statut du moniteur

ValeurDescription
UPLe moniteur fonctionne normalement
DOWNLe moniteur a échoué
DEGRADEDLe moniteur rencontre des problèmes
UNKNOWNL’état du moniteur ne peut pas être déterminé

Récupérer les moniteurs

Ce point de terminaison permet de parcourir la liste de tous les moniteurs existants.

Point de terminaison :

GET /:page_id/monitors

Paramètres de requête

ParamètreTypeValeur par défautDescription
pagenumber1Le numéro de page à récupérer.
limitnumber100Le nombre de moniteurs par page.
searchstringnullTerme de recherche pour filtrer les résultats.
statusenumnullFiltre de statut ('UP', 'DOWN', 'UNKNOWN', 'DEGRADED').

Exemple de requête

GET /1/monitors?limit=3&page=2&status=DOWN

Exemple de réponse

{
"monitors": [{ "...": "monitor objects" }],
"total": 10,
"page": 3,
"totalPages": 5,
"limit": 2
}

Créer un moniteur

Point de terminaison :

POST /monitors

Exemple de requête

{
"pageId": "page123",
"url": "https://example.com",
"httpMethod": "GET",
"body": null,
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer token"
},
"queryParams": {
"search": "test",
"limit": "10"
},
"basicAuth": {
"username": "user",
"password": "password"
},
"type": "HTTP",
"assertions": [
{
"type": "STATUSCODE",
"comparison": "EQUALS",
"selector": null,
"target": "200"
}
],
"alerts": ["alert-id-1", "alert-id-2"],
"name": "Example Monitor",
"locations": "US_EAST_1",
"checksInterval": 300,
"createComponent": true,
"createMetric": true,
"onFail": {
"createIncident": true,
"createOutageDuration": true,
"publishIncident": true,
"notifySubscribers": true
},
"onRecover": {
"resolveIncident": true,
"resolveOutageDuration": true,
"publishIncident": true,
"notifySubscribers": true
}
}

Exemple de réponse

{
"monitor": {
"pageId": "page123",
"url": "https://example.com",
"httpMethod": "GET",
"body": null,
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer token"
},
"queryParams": {
"search": "test",
"limit": "10"
},
"basicAuth": {
"username": "user",
"password": "password"
},
"type": "HTTP",
"assertions": [
{
"id": "assertion1",
"type": "STATUSCODE",
"comparison": "EQUALS",
"selector": null,
"target": "200"
}
],
"alerts": ["alert1", "alert2"],
"name": "Example Monitor",
"locations": "US_EAST_1",
"checksInterval": 300,
"createComponent": true,
"createMetric": true,
"onFail": {
"createIncident": true,
"createOutageDuration": true,
"publishIncident": true,
"notifySubscribers": true
},
"onRecover": {
"resolveIncident": true,
"resolveOutageDuration": true,
"publishIncident": true,
"notifySubscribers": true
},
"createdAt": "2023-08-08T12:00:00Z",
"updatedAt": "2023-08-08T12:00:00Z"
},
"message": "Monitor created successfully"
}

Mettre à jour un moniteur

Point de terminaison :

PUT /monitors/:id

Exemple de requête

{
"url": "https://updated.com",
"name": "Updated Monitor Name"
}

Exemple de réponse

{
"monitor": {
"pageId": "page123",
"url": "https://updated.com",
"httpMethod": "GET",
"body": null,
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer token"
},
"queryParams": {
"search": "test",
"limit": "10"
},
"basicAuth": {
"username": "user",
"password": "password"
},
"type": "HTTP",
"assertions": [
{
"id": "assertion1",
"type": "STATUSCODE",
"comparison": "EQUALS",
"selector": null,
"value": "200"
}
],
"alerts": ["alert1", "alert2"],
"name": "Updated Monitor Name",
"locations": "US_EAST_1",
"checksInterval": 300,
"createComponent": true,
"createMetric": true,
"onFail": {
"createIncident": true,
"createOutageDuration": true,
"publishIncident": true,
"notifySubscribers": true
},
"onRecover": {
"resolveIncident": true,
"resolveOutageDuration": true,
"publishIncident": true,
"notifySubscribers": true
},
"createdAt": "2023-08-08T12:00:00Z",
"updatedAt": "2023-08-08T12:00:00Z"
},
"message": "Monitor updated successfully"
}

Supprimer un moniteur

Point de terminaison :

DELETE /monitors/:id

Exemple de requête

DELETE /monitors/monitor-id-1

Exemple de réponse

{
"message": "Monitor deleted successfully."
}

Récupérer les journaux d’un moniteur

Point de terminaison :

GET /monitors/:id/logs

Paramètres de requête

ParamètreTypeValeur par défautDescription
limitnumber100Le nombre d’éléments par page. Ne peut pas dépasser 1000.
pagenumber1Le numéro de page à récupérer.
monitorIdstring-L’ID du moniteur.
locationstringnullL’emplacement du moniteur.
createdAtstring | object | numbernullLa date de création. Peut être une chaîne, un nombre ou un objet avec les champs gte et lte.
isSuccessfulbooleannullIndique si la vérification a réussi.
isSSLCheckbooleannullIndique si la vérification est une vérification SSL.
httpStatusCodestringnullLe code de statut HTTP de la réponse.
status('UP', 'DOWN', 'UNKNOWN', 'DEGRADED')nullLe statut du moniteur.
dnsTimestring | number | objectnullTemps de résolution DNS.
tcpTimestring | number | objectnullTemps d’établissement de la connexion TCP.
tlsTimestring | number | objectnullTemps de la poignée de main TLS.
firstByteTimestring | number | objectnullTemps de réception du premier octet.
downloadTimestring | number | objectnullTemps de téléchargement.
responseTimestring | number | objectnullTemps de réponse total.
performanceTimestring | number | objectnullTemps de performance.
accessabilityScorestring | number | objectnullScore d’accessibilité.
seoScorestring | number | objectnullScore SEO.
bestPracticesScorestring | number | objectnullScore de bonnes pratiques.
successfulAssertionsstring | number | objectnullNombre d’assertions réussies.
sortstringchronologiquementChamp de tri.

Exemple de requête

GET /monitors/monitor-id-1/logs?limit=100&page=1

Exemple de réponse

{
"monitorLogs": [
// {monitor log object},
// {monitor log object 2}
],
"total": 478,
"page": 1,
"totalPages": 5,
"limit": 100
}

Exécuter la vérification d’un moniteur par ID

Point de terminaison :

GET /monitors/:id/run

Paramètres de requête

ParamètreTypeValeur par défautDescription
location'US_EAST_1', 'EU_CENTRAL_1', 'AP_NORTHEAST_1', 'AP_SOUTHEAST_2', 'CA_CENTRAL_1'-L’emplacement du moniteur. Doit être l’une des valeurs indiquées.
retrybooleanfalseIndique si l’opération doit être réessayée. Facultatif.
monitorLogIdstringnullL’identifiant unique du journal de moniteur. Facultatif.

Exemple de requête

GET /monitors/monitor-id-1/run?monitorId=abc123&location=US_EAST_1&retry=true&monitorLogId=log456

Exemple de réponse

{
"status": "success",
"message": "Monitor check run successfully."
}

Créer une alerte de moniteur

Point de terminaison :

POST /monitor-alerts

Exemple de requête

{
"type": "EMAIL",
"pageId": "page123",
"recipient": "user@example.com",
"recipientWorkspace": "workspace123",
"whenFails": true,
"whenRecovers": true,
"whenDegrades": false,
"whenSslExpires": true,
"sslExpiresInDays": 30,
"monitors": ["monitor1", "monitor2"],
"metadata": "Additional information about the alert"
}

Exemple de réponse

{
"monitor": {
"id": "alert123",
"siteId": "site123",
"type": "EMAIL",
"recipient": "user@example.com",
"whenFails": true,
"whenRecovers": true,
"whenDegrades": false,
"whenSslExpires": true,
"sslExpiresInDays": 30,
"monitors": [{ "id": "monitor1" }, { "id": "monitor2" }],
"createdAt": "2023-08-08T12:00:00Z",
"updatedAt": "2023-08-08T12:00:00Z",
"metadata": "Additional information about the alert"
},
"message": "Monitor Alert created successfully"
}

Mettre à jour une alerte de moniteur

Point de terminaison :

PUT /monitor-alerts/:id

Exemple de requête

{
"type": "EMAIL",
"monitors": ["monitor-1-id", "monitor-2-id", "monitor-3-id"]
}

Exemple de réponse

{
"monitor": {
"type": "EMAIL",
"pageId": "page123",
"recipient": "user@example.com",
"recipientWorkspace": "workspace123",
"whenFails": true,
"whenRecovers": true,
"whenDegrades": false,
"whenSslExpires": true,
"sslExpiresInDays": 30,
"monitors": ["monitor-1-id", "monitor-2-id"],
"metadata": "Additional information about the alert"
},
"message": "Monitor alert updated successfully."
}

Récupérer les alertes de moniteur

Point de terminaison :

GET /:page_id/monitor-alerts

Paramètres de requête

ParamètreTypeValeur par défautDescription
limitnumber100Le nombre d’éléments par page.
pagenumber1Le numéro de page à récupérer.

Exemple de requête

GET /1/monitor-alerts?limit=2&page=3

Exemple de réponse

{
"monitorAlerts": [
{...monitor alert objects}
],
"total": 27,
"page": 3,
"totalPages": 14,
"limit": 2
}

Supprimer une alerte de moniteur

Point de terminaison :

DELETE /monitor-alerts/:id

Exemple de requête

DELETE /monitor-alerts/alert-id-1

Exemple de réponse

{
"message": "Monitor alert deleted successfully."
}

Créer un groupe de moniteurs

Point de terminaison :

POST /monitors-groups

Exemple de requête

{
"pageId": "page123",
"name": "Example Name",
"childId": "child456"
}

Exemple de réponse

{
"monitor": {
"id": "group123",
"name": "Example Name",
"siteId": "site123",
"collapsed": false,
"monitors": [{ "id": "monitor1" }, { "id": "monitor2" }],
"groupId": "parentGroup123",
"children": [
{ "id": "childGroup1", "name": "Child Group 1" },
{ "id": "childGroup2", "name": "Child Group 2" }
],
"order": 1,
"createdAt": "2023-08-08T12:00:00Z",
"updatedAt": "2023-08-08T12:00:00Z",
"parents": ["parent1", "parent2"],
"componentId": "component123"
},
"message": "Monitor group created successfully."
}

Mettre à jour un groupe de moniteurs

Point de terminaison :

PUT /monitors-groups/:id

Exemple de requête

{
"name": "Updated Monitor Group Name"
}

Exemple de réponse

{
"monitor": {
"id": "group123",
"name": "Updated Monitor Group Name",
"siteId": "site123",
"collapsed": true,
"monitors": [{ "id": "monitor1" }, { "id": "monitor2" }],
"groupId": "parentGroup123",
"children": [
{ "id": "childGroup1", "name": "Child Group 1" },
{ "id": "childGroup2", "name": "Child Group 2" }
],
"order": 1,
"createdAt": "2023-08-08T12:00:00Z",
"updatedAt": "2023-08-08T12:00:00Z",
"parents": ["parent1", "parent2"],
"componentId": "component123"
},
"message": "Monitor group updated successfully."
}

Supprimer un groupe de moniteurs

Point de terminaison :

DELETE /monitors-groups/:id

Exemple de requête

DELETE /monitors-groups/group-id-1

Exemple de réponse

{
"message": "Monitor group deleted successfully."
}

Ajouter des moniteurs à un groupe

Point de terminaison :

POST /monitors-groups/:id/monitors

Exemple de requête

{
"monitors": ["monitor1", "monitor2", "monitor3"]
}

Exemple de réponse

{
"message": "Monitors added to the group successfully."
}

Exécuter la vérification d’un groupe de moniteurs

Point de terminaison :

GET /monitors-groups/:id/run

Paramètres de requête

ParamètreTypeValeur par défautDescription
location'US_EAST_1', 'EU_CENTRAL_1', 'AP_NORTHEAST_1', 'AP_SOUTHEAST_2', 'CA_CENTRAL_1'-L’emplacement du moniteur. Doit être l’une des valeurs indiquées.
retrybooleanfalseIndique si l’opération doit être réessayée. Facultatif.
monitorLogIdstringnullL’identifiant unique du journal de moniteur. Facultatif.

Exemple de requête

GET /monitors-groups/group-id-1/run

Exemple de réponse

{
"result": "OK",
"monitorLogId": "monitor-log-id-1"
}

Moniteurs cron

Les moniteurs cron suivent les tâches planifiées via des pings HTTP. Pour la configuration produit et l’utilisation dans le tableau de bord, voir Surveillance cron.

Valeurs possibles des champs

Statut du moniteur cron

ValeurDescription
UPLe moniteur fonctionne normalement
DOWNLe moniteur a échoué
DEGRADEDLe moniteur rencontre des problèmes
UNKNOWNL’état du moniteur ne peut pas être déterminé

État du moniteur cron

ValeurDescription
ACTIVELe moniteur est vérifié activement
PAUSEDLes vérifications du moniteur sont en pause
MUTEDLe moniteur est en sourdine (aucune notification)

Statut de journal de moniteur cron

ValeurDescription
SUCCESSLa tâche s’est terminée avec succès
FAILURELa tâche a explicitement signalé un échec
MISSEDLa tâche n’a pas envoyé de ping dans la fenêtre attendue
LATELa tâche a envoyé un ping après la période mais dans le délai de grâce
STARTEDLa tâche a signalé son démarrage (mesure de la durée d’exécution)

Période et délai de grâce

period et grace sont exprimés en secondes. period est la fréquence d’exécution attendue de la tâche ; grace est le temps supplémentaire accordé avant que le moniteur soit marqué comme indisponible.

Récupérer les moniteurs cron

Point de terminaison :

GET /:page_id/monitors/cron

Paramètres de requête

ParamètreTypeValeur par défautDescription
limitnumber100Le nombre de moniteurs cron par page. Maximum 100.
pagenumber1Le numéro de page.
searchstringnullTerme de recherche pour filtrer les résultats par nom.
statusenumnullFiltre de statut ('UP', 'DOWN', 'UNKNOWN', 'DEGRADED').

Exemple de requête

GET /page123/monitors/cron?limit=10&page=1&status=DOWN

Exemple de réponse

{
"cronMonitors": [
{
"id": "cron-abc123",
"name": "Daily backup",
"slug": "my-page-x7k2m9n4p1q8w3e5",
"period": 86400,
"grace": 3600,
"status": "UP",
"state": "ACTIVE",
"siteId": "page123",
"order": 1,
"groupId": null,
"componentId": "component-id-1",
"onFailCreateIncident": true,
"onFailCreateOutageDuration": false,
"onFailPublishIncident": true,
"onFailNotifySubscribers": true,
"onRecoverResolveIncident": true,
"onRecoverResolveOutageDuration": false,
"onRecoverPublishIncident": true,
"onRecoverNotifySubscribers": true,
"createTemplateId": null,
"resolveTemplateId": null,
"createdAt": "2024-01-15T08:00:00.000Z",
"updatedAt": "2024-01-15T08:00:00.000Z"
}
],
"total": 1,
"page": 1,
"totalPages": 1,
"limit": 10
}

Créer un moniteur cron

Point de terminaison :

POST /monitors/cron

Exemple de requête

{
"pageId": "page123",
"name": "Daily backup",
"period": 86400,
"grace": 3600,
"alerts": ["alert-id-1", "alert-id-2"],
"createComponent": true,
"onFail": {
"createIncident": true,
"createOutageDuration": false,
"publishIncident": true,
"notifySubscribers": true
},
"onRecover": {
"resolveIncident": true,
"resolveOutageDuration": false,
"publishIncident": true,
"notifySubscribers": true
}
}

Exemple de réponse

{
"cronMonitor": {
"id": "cron-abc123",
"name": "Daily backup",
"slug": "my-page-x7k2m9n4p1q8w3e5",
"period": 86400,
"grace": 3600,
"status": "UP",
"state": "ACTIVE",
"siteId": "page123",
"order": 1,
"groupId": null,
"componentId": "component-id-1",
"onFailCreateIncident": true,
"onFailCreateOutageDuration": false,
"onFailPublishIncident": true,
"onFailNotifySubscribers": true,
"onRecoverResolveIncident": true,
"onRecoverResolveOutageDuration": false,
"onRecoverPublishIncident": true,
"onRecoverNotifySubscribers": true,
"createTemplateId": null,
"resolveTemplateId": null,
"createdAt": "2024-01-15T08:00:00.000Z",
"updatedAt": "2024-01-15T08:00:00.000Z"
},
"message": "Cron monitor created successfully."
}

La réponse contient un slug. Utilisez-le pour construire les URL de ping de votre tâche. Le premier ping réussi planifie la vérification en arrière-plan.

Mettre à jour un moniteur cron

Point de terminaison :

PUT /monitors/cron/:id

Exemple de requête

{
"name": "Daily backup (updated)",
"period": 43200,
"grace": 1800,
"state": "PAUSED",
"alerts": ["alert-id-1"],
"onFail": {
"notifySubscribers": false
}
}

Exemple de réponse

{
"cronMonitor": {
"id": "cron-abc123",
"name": "Daily backup (updated)",
"slug": "my-page-x7k2m9n4p1q8w3e5",
"period": 43200,
"grace": 1800,
"status": "UP",
"state": "PAUSED",
"siteId": "page123",
"order": 1,
"groupId": null,
"componentId": "component-id-1",
"onFailCreateIncident": true,
"onFailCreateOutageDuration": false,
"onFailPublishIncident": true,
"onFailNotifySubscribers": false,
"onRecoverResolveIncident": true,
"onRecoverResolveOutageDuration": false,
"onRecoverPublishIncident": true,
"onRecoverNotifySubscribers": true,
"createTemplateId": null,
"resolveTemplateId": null,
"alerts": [
{
"id": "alert-id-1",
"type": "EMAIL",
"recipient": "ops@example.com"
}
],
"createdAt": "2024-01-15T08:00:00.000Z",
"updatedAt": "2024-01-16T10:30:00.000Z"
},
"message": "Cron monitor updated successfully."
}

Supprimer un moniteur cron

Point de terminaison :

DELETE /monitors/cron/:id

Exemple de requête

DELETE /monitors/cron/cron-abc123

Exemple de réponse

{
"cronMonitor": {
"id": "cron-abc123",
"name": "Daily backup",
"slug": "my-page-x7k2m9n4p1q8w3e5",
"period": 86400,
"grace": 3600,
"status": "UP",
"state": "ACTIVE",
"siteId": "page123",
"order": 1,
"groupId": null,
"componentId": "component-id-1",
"onFailCreateIncident": true,
"onFailCreateOutageDuration": false,
"onFailPublishIncident": true,
"onFailNotifySubscribers": true,
"onRecoverResolveIncident": true,
"onRecoverResolveOutageDuration": false,
"onRecoverPublishIncident": true,
"onRecoverNotifySubscribers": true,
"createTemplateId": null,
"resolveTemplateId": null,
"createdAt": "2024-01-15T08:00:00.000Z",
"updatedAt": "2024-01-15T08:00:00.000Z"
},
"message": "Cron monitor deleted successfully."
}

Récupérer les journaux d’un moniteur cron

Point de terminaison :

GET /monitors/cron/:id/logs

Paramètres de requête

ParamètreTypeValeur par défautDescription
limitnumber100Le nombre de journaux par page. Maximum 127.
pagenumber1Le numéro de page. Maximum 1000.
startDatestringil y a 1 anDate de début ISO 8601 de la plage de journaux.
endDatestringmaintenantDate de fin ISO 8601 de la plage de journaux.
importanceenumnullFiltrer les journaux par importance ('all', 'important').

Exemple de requête

GET /monitors/cron/cron-abc123/logs?limit=50&page=1&importance=important

Exemple de réponse

{
"logs": [
{
"id": "log-xyz789",
"monitorId": "cron-abc123",
"status": "SUCCESS",
"requestType": "GET",
"agent": "curl/8.4.0",
"ipAddress": "203.0.113.10",
"createdAt": "2024-01-16T06:00:00.000Z",
"startedAt": "2024-01-16T05:59:58.000Z"
}
],
"page": 1
}

Récupérer le résumé d’un moniteur cron

Point de terminaison :

GET /monitors/cron/:id/summary

Exemple de requête

GET /monitors/cron/cron-abc123/summary

Exemple de réponse

{
"summary": {
"totalLogs": 120,
"totalFailedLogs": 3,
"availability": 97.5,
"oneDayAvailability": 100,
"previousDayAvailability": 100,
"sevenDayAvailability": 98.2,
"previousSevenDayAvailability": 96.1,
"thirtyDayAvailability": 97.5,
"previousThirtyDayAvailability": 95.8,
"lastSuccess": "2024-01-16T06:00:00.000Z",
"lastFailure": "2024-01-10T06:00:00.000Z",
"lastStarted": null,
"upSince": "2024-01-10T07:00:00.000Z",
"downSince": null
}
}

Points de terminaison de ping

Ces points de terminaison ne nécessitent pas d’authentification. Le slug du moniteur fait office de secret.

Vous pouvez envoyer un ping via l’URL de base de l’API ou l’hôte cron dédié :

  • Succès : https://cron.instatus.com/{slug} ou GET / POST / HEAD /monitors/cron/{slug}
  • Échec : https://cron.instatus.com/{slug}/fail ou GET / POST / HEAD /monitors/cron/{slug}/fail
  • Début : https://cron.instatus.com/{slug}/start ou GET / POST / HEAD /monitors/cron/{slug}/start

Envoyez un ping de succès chaque fois que votre tâche se termine à l’heure prévue. Envoyez un ping de début avant l’exécution puis un ping de succès ou d’échec à la fin pour enregistrer la durée d’exécution.

Exemple de ping de succès

curl https://cron.instatus.com/my-page-x7k2m9n4p1q8w3e5

Exemple de réponse

{
"id": "log-xyz789",
"monitorId": "cron-abc123",
"status": "SUCCESS",
"requestType": "GET",
"agent": "curl/8.4.0",
"ipAddress": "203.0.113.10",
"createdAt": "2024-01-16T06:00:00.000Z"
}

Si le slug est invalide, la réponse est :

{
"message": "Monitor not found"
}