Asset-Logs-API

Ruft Aktivitätsprotokolleinträge ab, die für ein Gerät erfasst wurden. Protokolleinträge werden automatisch von der Plattform geschrieben, wenn Remote-Aktionen durchgeführt, Direktsitzungen wie Terminal oder Remote-Desktop geöffnet, automatisierte Tasks ausgeführt, Patch-Aktivitäten verzeichnet oder Software auf einem Gerät verteilt wird.

Die vollständige, stets aktuelle Liste der Endpoints, Parameter und Antwortfelder für die Version, die du betreibst, findest du in der interaktiven OpenAPI-Oberfläche (Swagger) unter https://<deine-octoja-instanz>/openapi/index.html.

Endpoint

Request Body

{ "assetId": "uuid", "sourceType": "RealtimeAction", "sourceId": "string", "userId": "uuid", "since": "2026-01-01T00:00:00Z", "page": 1, "pageSize": 50 }

Erforderlich: since (nur Einträge ab diesem Zeitpunkt zurückgeben). Zusätzlich muss entweder assetId oder sourceType (oder beides) angegeben werden. sourceId filtert innerhalb eines angegebenen sourceType und ist nur zusammen mit sourceType gültig; ohne sourceType antwortet der Server mit 400. page hat den Standardwert 1 und pageSize den Standardwert 50 (maximal 500). Du kannst die Ergebnisse außerdem mit severity und einer Freitext-search einschränken sowie die Sortierung über sortBy (Timestamp oder SourceType) und sortDir (Asc oder Desc) steuern. Die vollständige Feldliste und die Typen findest du in Swagger.

Quelltypen

sourceType ist einer aus einer festen Menge von Werten (siehe Swagger), die jeweils für eine andere Art von Aktivität geschrieben werden:

• RealtimeAction — ein Benutzer löst eine Remote-Aktion auf dem Gerät aus. Dazu zählen die Dienststeuerung (starten, stoppen, neu starten, Starttyp ändern), einen Prozess beenden, eine Benachrichtigung an den angemeldeten Benutzer senden, Registry-Bearbeitungen, lokale Benutzerkonten (anlegen, aktivieren oder deaktivieren, Kennwort ändern), Active-Directory-Benutzer und Gruppenmitglieder, Ad-hoc-Skripte und Checks auf Abruf, Paketinstallation und -deinstallation, die Verwaltung entfernter Dateien (umbenennen, löschen, zippen, entpacken, Verzeichnis anlegen), Datenträgerbereinigung, Inventarisierungsläufe, Agent-Updates, VMware- und Hyper-V-Aktionen zum Ein- und Ausschalten sowie Snapshots und Prüfpunkte, das Gerät aufwecken und die Web-Konsole öffnen.
• DirectSession — eine Direktsitzung wird auf einem Gerät geöffnet: Terminal, Remote-Desktop, Herunter- oder Hochladen von Dateien, ein Scan der Speicheranalyse, das Herunterladen von Protokollen, eine Registry-Suche oder ein Ereignisprotokoll-Export.
• Task — ein automatisierter Task wird auf dem Gerät ausgeführt, zum Beispiel ein Automatisierungslauf, eine Agent-Registrierung oder ein Agent-Update.
• WindowsPatchManagement — Windows-Patch-Aktivität auf dem Gerät.
• MacOSPatchManagement — macOS-Patch-Aktivität auf dem Gerät.
• SoftwareDeployment — Software-Deployment-Aktivität auf dem Gerät.
• Configuration — ein Benutzer ändert die Konfiguration des Geräts: Geräteeinstellungen, Check-Zuweisungen, ob eine Schwachstelle ignoriert wird, oder ein Wartungsfenster wird gesetzt oder aufgehoben.

Antwort

{ "items": [ { "id": "uuid", "assetId": "uuid", "timestamp": "2026-04-06T10:00:00Z", "severity": "Info", "content": "Opened Terminal session abc-123.", "userId": "user-uuid", "userName": "Alice Example", "source": { "id": "session-abc-123", "sourceType": "DirectSession" } } ], "total": 123 }

Gibt ein seitenweises Ergebnis zurück. items enthält die Protokolleinträge der angeforderten Seite (standardmäßig nach Zeitstempel absteigend sortiert), und total ist die Gesamtzahl der übereinstimmenden Einträge über alle Seiten hinweg. Wichtige Felder:

• severity ist einer der Werte Info, Warning oder Error.
• userId / userName sind null, wenn das Ereignis keinen ausführenden Benutzer hatte; userName wird beim Lesen des Protokolls aus dem Benutzerdatensatz aufgelöst und zeigt daher den aktuellen Anzeigenamen dieses Benutzers — existiert der Benutzer nicht mehr, ist das Feld null.
• source.id gibt an, wodurch der Eintrag erzeugt wurde, nicht wer ihn ausgelöst hat. Einträge vom Typ RealtimeAction, Configuration und Task verwenden einen festen Schlüssel (zum Beispiel restart-service, device-check, automation-run); Sitzungs-, Patch- und Deployment-Einträge verwenden in der Regel die ID der Sitzung, des Patch-Zyklus oder der Deployment-Konfiguration.