Pings

GET/api/v1/pings

Liest die Probe-Historie, die ein bestimmter VPS-Agent von seiner eigenen Netzposition aus ausführt. Diese Quelle ist unabhängig von Cloudflare-Aktivchecks und externen Latency-Agents.

Zielprotokolle

Die Admin-UI behält vorhandene Zielfelder. Seit Agent v1.0.44 wählt das Schema die Probe-Methode:

Syntax	Protokoll	Erfolgsbedingung
host:port	TCP	TCP-Verbindung innerhalb 1 s
tcp://host:port	TCP	TCP-Verbindung innerhalb 1 s
http://host/path	HTTP	Antwort 200-399 innerhalb 1 s
https://host/path	HTTPS	Antwort 200-399 innerhalb 1 s

Ziele dürfen keine HTTP-Benutzernamen oder Passwörter enthalten. Der Agent wirbt tcp,http; 1.0.44 akzeptiert keine neuen icmp://-Ziele mehr, und vererbte ICMP-Ziele werden nicht verteilt.

Query-Parameter

Parameter	Pflicht	Standard	Zweck
agent_id	ja	leer	der Agent, der die Probes ausführt
hours	nein	24	Standard max. 72 h, Deployment-Deckel 168 h
max_points_per_target	nein	360	Punkte je Ziel auf normalen Kurven; nicht positiv fällt zurück, harter Deckel 2000
format	nein	row	series liefert kompakte Serien je Ziel
include_loss	nein	0	1 liefert alle Roh-Verlustereignisse verlustfrei im Fenster

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

Antwortfelder

Feld	Zweck
targets[]	aktivierte Ziel-IDs, Namen, Farben
pings[]	begrenzte Zeilenhistorie; leer mit format=series
series	begrenzte kompakte Kurven je Ziel
ping_stats	Summen, Erfolge, Verlustrate aus Roh-Samples vor dem Downsampling
pings_raw_count	Punkte vor dem Downsampling
pings_downsampled	ob normale Kurven heruntergesampelt wurden
ping_interval_sec	aktuelles globales Probe-Intervall
loss_series	verlustfreie Verlust-Runs bei include_loss=1
loss_events_raw_count	von loss_series dargestellte Roh-Verlustereignisse
source	aktuelle Historienquelle

loss_series[] nutzt { target_id, t0, runs }; jeder Run ist [start_delta, step, count] mit Zeitstempeln t0 + start_delta + step * index (index von 0 bis count - 1). Verstreute Verluste werden nicht verworfen. Das integrierte Frontend zeichnet diese Ebene nicht mehr, zeigt aber Verlust je Ziel über ping_stats.

Fehlgeschlagene Punkte haben latency_ms: null; nie als 0 ms interpretieren. R2 hält rohe Telemetrie als maßgebliche Historie; optionaler Timeseries-Export ändert diesen Endpoint nicht, und Exportfehler blockieren nie Agent-ACK oder R2-Archivierung.

Anzeige-Hinweise

• Legende nutzt Namen aus targets[]; Daten sind per ID verknüpft.
• Latenzkurven nutzen begrenztes series; Zusammenfassungen je Ziel nutzen ping_stats.
• Für vollständige Verlustereignisse include_loss=1 anfordern und loss_series lesen.
• Keine neuen Probes bei offline Agent: erwartet.
• Pings nicht mit anderen Quellen zu beschriftungslosen Kurven verschmelzen.