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.
| Parameter | Meaning |
|---|---|
from, to | Unix milliseconds. Default: the last 24 hours. |
level | One or more levels, comma separated: error,critical |
category, message | The area and the event name. Several values with |, ! in front to exclude: message=!http_request_served |
user, session, install | An id |
env, platform | production, ios... Without them, every environment and platform. |
version, os, device, locale | The app version, the OS version (27.2.0), the device model and the locale |
country | Where the person is: the country of the address the events came from, else the region of the device's locale (es_ES is ES) |
verified | How an event is verified: server (sent with a server key), app_attest (sent by your Apple app, proven with App Attest), none (not verified) |
attr | path:value on an attribute, or path!:value to exclude. Repeat it for several. |
q | Text in the message or the area (any case), or an exact event, user, session or install id. Attributes aren't searched: use attr. |
limit | 1 to 1000, default 100 |
order | asc for oldest first |
cursor | The 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
doneOne 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
| Status | Meaning |
|---|---|
400 | A 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 |
401 | No key, or an unknown or revoked one |
403 | The key can't read (an ingest key) |
404 | No event with that id and ts |
429 | More 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.