Lorsque des utilisateurs d’un même pays signalent des problèmes alors que l’équipe constate un fonctionnement normal du service, il est particulièrement utile de vérifier les observations propres à leur région. L’API UptimeScout permet de demander l’historique d’un service donné à l’aide d’un code régional et de récupérer des intervalles accompagnés du nombre de mesures. On obtient ainsi un tableau vérifiable pour examiner le signalement : heure de l’intervalle, résolution, répartition des signaux et nombre d’échantillons.

Le scénario pratique consiste ici à diagnostiquer une éventuelle panne régionale. Les données d’entrée sont l’identifiant du service dans le catalogue UptimeScout, un code régional comme US ou GB et une fenêtre d’historique. Le résultat permet de comparer l’heure du signalement de l’utilisateur avec les observations du service. L’API décrit ces données comme des signaux de disponibilité observée ; la vérification du service aide à circonscrire la question, mais ne remplace pas les contrôles propres à l’application.
Confirmez d’abord le service et la région
Commencez par le catalogue : trouvez le service voulu par son nom ou à l’aide de la recherche, puis notez son ID exact. La spécification OpenAPI d’UptimeScout décrit la recherche via GET /v1/services et les paramètres q, service, region, limit et offset. Pour un rapport de diagnostic, il vaut mieux conserver l’ID plutôt que le seul nom affiché : les requêtes ultérieures cibleront ainsi le même élément du catalogue.
La région est indiquée séparément par un code à deux lettres. Il est important de l’enregistrer avec le résultat : une réponse filtrée sur US et une réponse sans filtre régional ne répondent pas à la même question. Si la description doit être affichée en français, le paramètre lang=fr contrôle sa localisation, tandis que le paramètre region sélectionne les observations. La documentation distingue explicitement ces deux fonctions.
Demandez l’historique plutôt qu’un statut unique
Pour analyser un incident, utilisez /v1/history avec le paramètre service obligatoire et la region choisie. Le paramètre hours définit la fenêtre d’historique ; la spécification accepte des valeurs de 1 à 2160 heures. La requête prévoit également lang. Selon OpenAPI, l’authentification se fait au moyen d’une licence selon le schéma Bearer. En pratique, conservez la clé dans une variable d’environnement et ne l’inscrivez pas dans les journaux de requêtes.
import os
import requests
response = requests.get(
"https://api.uptimescout.com/v1/history",
headers={"Authorization": f"Bearer {os.environ['UPTIMESCOUT_LICENSE_KEY']}"},
params={"service": "github", "region": "GB", "hours": 24, "lang": "ru"},
timeout=30,
)
response.raise_for_status()
data = response.json()
print(data)
Il s’agit d’un exemple minimal de requête, et non du résultat publié d’une enquête réelle. L’identifiant github et la région GB sont donnés à titre d’exemple : avant d’utiliser la requête, choisissez le service et la région correspondant à votre situation. Il est utile de conserver la réponse entière en JSON et d’ajouter l’heure de réception ainsi que la description de la requête dans des champs distincts de votre système d’audit. Vous pourrez ainsi reproduire l’analyse et déterminer précisément quel instantané de données a été utilisé.
La résolution et les lacunes font partie du résultat
Dans le tableau history, les champs importants sont observed_at, resolution_seconds, aggregated, samples et counts. La résolution indique la durée de l’intervalle temporel ; samples indique le nombre d’observations intégrées à l’agrégat, tandis que counts en contient la répartition des signaux. Examinez ces champs ensemble : une ligne reposant sur un petit nombre d’échantillons n’a pas le même poids analytique qu’un agrégat fondé sur un grand nombre d’observations.

UptimeScout décrit l’historique comme une série de créneaux temporels dont la granularité varie selon la fenêtre choisie : intervalles d’une minute ou de cinq minutes pour les courtes périodes, horaires pour une journée et quotidiens pour les longues périodes. Les anciens agrégats conservés peuvent avoir une résolution plus grossière. Ne concluez donc pas qu’« une panne a commencé exactement à cette minute » si la ligne correspond à un agrégat horaire ou journalier. Utilisez la valeur réelle de resolution_seconds ainsi que les champs effective_start et history_resolution de la réponse pour délimiter ce que les données permettent d’affirmer.
Considérez tout intervalle manquant comme inconnu. La spécification demande explicitement de traiter les lacunes comme des intervalles inconnus : une absence dans l’historique n’indique, à elle seule, ni un fonctionnement normal ni une panne. Cette règle simple évite, dans les rapports, de remplir à tort les lacunes avec un statut « vert » ou des zéros.
Comparez l’historique au signal actuel
Pour vérifier l’état au moment du signalement, demandez /v1/status pour le même service et la même région. Dans l’objet du service, examinez ensemble status, observed_at et stale ; la documentation présente ces champs comme un moyen de comprendre l’état et la fraîcheur du signal. Le statut de premier niveau concerne le résultat de la requête API, tandis que service.status décrit le signal de disponibilité du service concerné. Cette distinction est particulièrement utile dans les rapports automatisés : une réponse HTTP réussie et l’état d’un service externe sont deux choses différentes.
Pour plusieurs dépendances, vous pouvez passer à /v1/statuses, puis consulter l’historique uniquement pour les services et les régions où une anomalie est apparue. La spécification propose également /v1/summary et /v1/incidents. Pour le diagnostic de ce dernier endpoint, tenez compte de son rôle exact : il renvoie de récents signaux d’anomalie élevés, et non des incidents confirmés par le fournisseur lui-même. Le résultat constitue donc un motif de vérification, pas une conclusion définitive sur la cause.
Formulez vos conclusions sans conjectures
Dans la ligne du rapport, consignez le service ID, la region, la période de la requête, observed_at, resolution_seconds, samples, counts et l’indication des éventuelles lacunes. Ajoutez le lien vers le signalement ou l’incident interne séparément des champs de l’API. Comparez ensuite la plage temporelle avec les journaux de l’application, les traces régionales et le message de l’utilisateur. Si les limites temporelles de l’agrégat dépassent la durée de l’incident, formulez le résultat en conséquence : les observations de la région sélectionnée pour la fenêtre donnée contiennent tels signaux, avec telle résolution et tel nombre d’échantillons.
Cette analyse aide la personne d’astreinte à choisir la suite : vérifier le service externe du point de vue régional, ou poursuivre le diagnostic de l’application et du réseau de l’utilisateur. Sa reproductibilité dépend de la conservation des paramètres de requête et du JSON d’origine ; la fiabilité des conclusions temporelles dépend, elle, de la prise en compte explicite de la résolution, des samples et des intervalles inconnus. Pour un cas de disponibilité, c’est le résultat pratique : non pas une simple étiquette de statut actuel, mais un relevé délimité par région et par période qu’un collègue peut vérifier à son tour.