Read API
Frag die Events eines Projekts mit einem Lese-Schlüssel aus einem Skript ab.
Das Dashboard ist ein Weg, Events zu lesen. Die Read API ist der andere: dieselben Filter, als JSON, für ein Skript, ein Notebook, einen geplanten Job oder einen Agenten.
Authentifizierung
Wähle auf der Seite API keys des Projekts New key und setze What it can do auf
Read events. Der Schlüssel beginnt mit lyr_read_ und wird einmal angezeigt. Sende ihn als
Bearer-Token an https://app.lyrelog.com. Die Beispiele unten legen ihn in einer Shell-Variable
ab:
export LYRELOG_READ_KEY=lyr_read_...
curl -s https://app.lyrelog.com/v1/events \
-H "Authorization: Bearer $LYRELOG_READ_KEY"Ein Lese-Schlüssel sieht jedes Event seines Projekts und sonst nichts. Bewahre ihn auf einem
Server auf: Wer ihn hat, kann die Events der Personen lesen, die deine App nutzen. Ein Schlüssel mit Full access
kann ebenfalls lesen; ein Ingest-Schlüssel nicht (403).
Events auflisten
GET /v1/events liefert die neuesten Events zuerst, 100 auf einmal, aus den letzten 24 Stunden,
sofern du nichts anderes angibst.
| Parameter | Bedeutung |
|---|---|
from, to | Unix-Millisekunden. Standard: die letzten 24 Stunden. |
level | Ein oder mehrere Levels, durch Kommas getrennt: error,critical |
category, message | Der Bereich und der Event-Name. Mehrere Werte mit |, ! davor zum Ausschließen: message=!http_request_served |
user, session, install | Eine ID |
env, platform | production, ios... Ohne sie: jede Umgebung und Plattform. |
version, os, device, locale | Die App-Version, die Version des Betriebssystems (27.2.0), das Gerätemodell und die Locale |
country | Wo die Person ist: das Land der Adresse, von der die Events kamen, sonst die Region der Locale des Geräts (es_ES ist ES) |
verified | Wie ein Event verifiziert ist: server (mit einem Server-Schlüssel gesendet), app_attest (von deiner Apple-App gesendet und mit App Attest bestätigt), key_attestation (von deiner Android-App gesendet und mit Key Attestation bestätigt), none (nicht verifiziert) |
attr | path:value auf ein Attribut oder path!:value zum Ausschließen. Für mehrere wiederholen. |
q | Text in der Message oder im Bereich (Groß- und Kleinschreibung egal) oder eine exakte Event-, Nutzer-, Session- oder Installations-ID. Attribute werden nicht durchsucht: Verwende attr. |
limit | 1 bis 1000, Standard 100 |
order | asc für die ältesten zuerst |
cursor | Der next_cursor der vorherigen Antwort, für die nächste Seite |
category, message, user, session, install, env, platform, version, os,
device, locale, country und verified nehmen mehrere durch | getrennte Werte („ist einer
von“) oder eine Liste mit ! davor („ist nicht“): os=26.4|27.2.0, platform=!web. Ein
attr-Wert nimmt ebenfalls | und wird mit ! nach dem Pfad ausgeschlossen:
attr=plan!:free|trial. Gerätemodelle enthalten Kommas (iPhone18,1), deshalb ist das
Trennzeichen |.
# Errors on iOS in production in the last hour
curl -s -G https://app.lyrelog.com/v1/events \
-H "Authorization: Bearer $LYRELOG_READ_KEY" \
--data-urlencode "level=error,critical" \
--data-urlencode "platform=ios" \
--data-urlencode "env=production" \
--data-urlencode "from=$(( ($(date +%s) - 3600) * 1000 ))"Die Antwort ist {"events": [...], "next_cursor": "..."}; auf der letzten Seite ist
next_cursor null. Jedes Event hat event_id, ts (Unix-Millisekunden), level,
category, message, user_id, install_id, session_id und attrs, dazu die Felder der
Resource (app_id, app_version, app_build, os_name, os_version, device_model,
locale, environment, platform), country und verified_by: "server", wenn das Event
mit einem Server-Schlüssel kam, "app_attest", wenn sich deine Apple-App mit App Attest
ausgewiesen hat, "key_attestation", wenn sich deine Android-App mit Key Attestation
ausgewiesen hat, "", wenn es nicht verifiziert ist (siehe
Verifizierte Events). Die Liste lässt die Payload weg: Frag ein
einzelnes Event ab, um sie zu bekommen.
Alle Seiten
Ein Cursor setzt nur die Abfrage fort, aus der er stammt: Sende dieselben Filter mit. Ohne from
und to wandert das Zeitfenster mit der Uhr, also leg beide fest, wenn du mehrere Seiten liest.
Dieses Beispiel liest jeden Fehler der letzten 7 Tage, die ältesten zuerst, 1000 auf einmal (es
braucht jq):
FROM=$(( ($(date +%s) - 7*86400) * 1000 )); TO=$(( $(date +%s) * 1000 )); CURSOR=""
while :; do
PAGE=$(curl -s -G https://app.lyrelog.com/v1/events \
-H "Authorization: Bearer $LYRELOG_READ_KEY" \
--data-urlencode "level=error,critical" --data-urlencode "order=asc" --data-urlencode "limit=1000" \
--data-urlencode "from=$FROM" --data-urlencode "to=$TO" ${CURSOR:+--data-urlencode "cursor=$CURSOR"})
echo "$PAGE" | jq -c '.events[]'
CURSOR=$(echo "$PAGE" | jq -r '.next_cursor // empty'); [ -z "$CURSOR" ] && break
doneEin einzelnes Event
GET /v1/events/{event_id}?ts={ts} liefert ein Event mit seiner ganzen Payload als
{"event": {...}}. Übergib den ts (Unix-Millisekunden), den die Liste geliefert hat: Events
werden nach Zeit gespeichert, mit der ID allein müsste man also alle durchsuchen.
curl -s -G "https://app.lyrelog.com/v1/events/6f1b2c3d-5a1e-4c1f-9e7a-0a1b2c3d4e5f" \
-H "Authorization: Bearer $LYRELOG_READ_KEY" \
--data-urlencode "ts=1794996000123"{"event":{"event_id":"6f1b2c3d-5a1e-4c1f-9e7a-0a1b2c3d4e5f","ts":1794996000123,"level":"error","category":"checkout","message":"payment_declined","user_id":"user-1","install_id":"","session_id":"2f9a...","app_id":"com.example.app","app_version":"2.0","app_build":"202611181200","os_name":"iOS","os_version":"27.2.0","device_model":"iPhone18,1","locale":"es_ES","country":"ES","environment":"production","platform":"ios","verified_by":"","attrs":{"code":51},"payload":{"response":"..."}}}Ein Feld, das die App nicht gesendet hat, ist ein leerer String. payload fehlt, wenn das Event
keine hat.
Limits und Fehler
| Status | Bedeutung |
|---|---|
400 | Ein Parameter ist falsch; der Body sagt, welcher. Zum Beispiel: from nicht vor to, ein Zeitraum über 400 Tage, mehr als 8 attr-Filter, mehr als 100 Werte in einem Filter, ein unbekanntes Level, limit außerhalb von 1 bis 1000, ein ungültiger cursor |
401 | Kein Schlüssel oder ein unbekannter oder widerrufener |
403 | Der Schlüssel kann nicht lesen (ein Ingest-Schlüssel) |
404 | Kein Event mit dieser ID und diesem ts |
429 | Mehr als 120 Anfragen pro Minute für diesen Schlüssel (Retry-After: 60); das Projekt führt bereits 4 Abfragen gleichzeitig aus, Dashboard und Schlüssel zusammen (Retry-After: 2); oder mehr als 60 unbekannte Schlüssel von deiner Adresse in 15 Minuten |
500 | {"error":"something went wrong on the server"}. Eine Abfrage, die länger als 15 Sekunden dauert, endet so: Grenze den Zeitraum ein oder füge Filter hinzu |
Ein Fehler kommt als {"error": "..."} zurück. Warte nach einem 429 die Zeit aus Retry-After
ab, bevor du es erneut versuchst.
Antworten werden nie gecacht (Cache-Control: no-store). Die API hat absichtlich keine
CORS-Header: Ein Lese-Schlüssel gehört nicht in einen Browser.