Pings

GET/api/v1/pings

Lit l'historique des sondes lancées par un Agent VPS spécifique depuis sa propre position réseau. Cette source est indépendante des sondes actives Cloudflare et des Agents de latence externe.

Protocoles de cible

L'interface admin conserve les champs de cible existants. Depuis l'Agent v1.0.44, le schéma sélectionne la méthode de sonde :

Syntaxe	Protocole	Condition de succès
host:port	TCP	connexion TCP en moins d'1 s
tcp://host:port	TCP	connexion TCP en moins d'1 s
http://host/path	HTTP	réponse 200-399 en moins d'1 s
https://host/path	HTTPS	réponse 200-399 en moins d'1 s

Les cibles ne doivent pas contenir de nom d'utilisateur ou mot de passe HTTP. L'Agent annonce tcp,http ; 1.0.44 n'accepte plus de nouvelles cibles icmp://, et les cibles ICMP héritées ne sont pas distribuées.

Paramètres de requête

Paramètre	Requis	Défaut	Rôle
agent_id	oui	vide	l'Agent qui exécute les sondes
hours	non	24	max par défaut 72 h, plafond de déploiement 168 h
max_points_per_target	non	360	points par cible sur les courbes régulières ; non positif retombe, plafond dur 2000
format	non	row	series renvoie des séries compactes par cible
include_loss	non	0	1 renvoie tous les événements de perte bruts sans perte dans la fenêtre

curl -fsSL 'https://YOUR-API/api/v1/pings?agent_id=vps-a&hours=6&format=series&include_loss=1'

Champs de réponse

Champ	Rôle
targets[]	ID, noms et couleurs des cibles activées
pings[]	historique de lignes borné ; vide avec format=series
series	courbes compactes bornées par cible
ping_stats	totaux, succès, taux de perte depuis les échantillons bruts pré-sous-échantillonnage
pings_raw_count	points avant sous-échantillonnage
pings_downsampled	indique un sous-échantillonnage des courbes régulières
ping_interval_sec	intervalle de sonde global courant
loss_series	runs de perte sans perte quand include_loss=1
loss_events_raw_count	événements de perte bruts représentés par loss_series
source	source d'historique courante

loss_series[] utilise { target_id, t0, runs } ; chaque run est [start_delta, step, count] avec horodatages t0 + start_delta + step * index (index de 0 à count - 1). Les pertes éparses ne sont pas abandonnées. Le frontend intégré ne dessine plus cette couche mais affiche la perte par cible via ping_stats.

Les points en échec ont latency_ms: null ; ne les interprétez jamais comme 0 ms. R2 conserve la télémétrie brute comme historique faisant foi ; l'export de séries temporelles optionnel ne change pas cet endpoint, et les échecs d'export ne bloquent jamais l'ACK Agent ni l'archivage R2.

Conseils d'affichage

• La légende utilise les noms de targets[] ; les données sont liées par ID.
• Les courbes de latence utilisent series borné ; les résumés par cible utilisent ping_stats.
• Pour les événements de perte complets, demandez include_loss=1 et lisez loss_series.
• Aucune nouvelle sonde tant que l'Agent est hors ligne : attendu.
• Ne fusionnez pas Pings avec d'autres sources en courbes sans étiquette.