Early accessBy invitation, and the SDKs aren't published yet.Ask for an invitation
Skip to Content
Docs

Read API

Query a project's events from a script with a read key.

The dashboard is one way to read events. The read API is the other: the same filters, as JSON, for a script, a notebook, a scheduled job or an agent.

Authentication

On the project's API keys page, choose New key and set What it can do to Read events. The key starts with lyr_read_ and is shown once. Send it as a bearer token to https://app.lyrelog.com. The examples below keep it in a shell variable:

export LYRELOG_READ_KEY=lyr_read_...
curl -s https://app.lyrelog.com/v1/events \
  -H "Authorization: Bearer $LYRELOG_READ_KEY"

A read key sees every event of its project and nothing else. Keep it on a server: anyone who has it can read your users' events. A Full access key reads too; an ingest key can't (403).

List events

GET /v1/events answers the newest events first, 100 at a time, from the last 24 hours unless you say otherwise.

ParameterMeaning
from, toUnix milliseconds. Default: the last 24 hours.
levelOne or more levels, comma separated: error,critical
category, messageThe area and the event name. Several values with |, ! in front to exclude: message=!http_request_served
user, session, installAn id
env, platformproduction, ios... Without them, every environment and platform.
version, os, device, localeThe app version, the OS version (27.2.0), the device model and the locale
countryWhere the person is: the country of the address the events came from, else the region of the device's locale (es_ES is ES)
verifiedHow an event is verified: server (sent with a server key), app_attest (sent by your Apple app, proven with App Attest), none (not verified)
attrpath:value on an attribute, or path!:value to exclude. Repeat it for several.
qText in the message or the area (any case), or an exact event, user, session or install id. Attributes aren't searched: use attr.
limit1 to 1000, default 100
orderasc for oldest first
cursorThe next_cursor of the previous answer, for the next page

category, message, user, session, install, env, platform, version, os, device, locale, country and verified take several values separated by | ("is any of"), or a list with ! in front ("is not"): os=26.4|27.2.0, platform=!web. An attr value takes | too, and is excluded with ! after the path: attr=plan!:free|trial. Device models contain commas (iPhone18,1), which is why the separator is |.

# 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 ))"

The answer is {"events": [...], "next_cursor": "..."}; next_cursor is null on the last page. Each event has event_id, ts (Unix milliseconds), level, category, message, user_id, install_id, session_id and attrs, plus the resource fields (app_id, app_version, app_build, os_name, os_version, device_model, locale, environment, platform), country and verified_by: "server" when the event came with a server key, "app_attest" when your Apple app proved itself with App Attest, "" when it isn't verified (see Verified events). The list leaves the payload out: ask for one event to get it.

Every page

A cursor only continues the query it came from: send the same filters with it. Without from and to, the window moves with the clock, so fix them when you read several pages. This reads every error of the last 7 days, oldest first, 1000 at a time (it needs 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
done

One event

GET /v1/events/{event_id}?ts={ts} answers one event, with its whole payload, as {"event": {...}}. Pass the ts (Unix milliseconds) the list gave you: events are stored by time, so the id alone would mean searching all of them.

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":"..."}}}

A field the app didn't send is an empty string. payload is left out when the event has none.

Limits and errors

StatusMeaning
400A parameter is wrong; the body says which. For example: from not before to, a range over 400 days, more than 8 attr filters, more than 100 values in one filter, an unknown level, limit outside 1 to 1000, a bad cursor
401No key, or an unknown or revoked one
403The key can't read (an ingest key)
404No event with that id and ts
429More than 120 requests a minute for this key (Retry-After: 60); the project already runs 4 queries at once, the dashboard and its keys together (Retry-After: 2); or more than 60 unknown keys from your address in 15 minutes
500{"error":"something went wrong on the server"}. A query that takes over 15 seconds ends this way: narrow the range or add filters

An error answers {"error": "..."}. Wait for Retry-After before trying again after a 429.

Answers are never cached (Cache-Control: no-store). The API has no CORS headers on purpose: a read key doesn't belong in a browser.