Events
GET /v1/events — query events with filters for app, level, date range, session, and more.
Query stored events with filters and cursor-based pagination.
GET /v1/events
List events with optional filters. Results are ordered by timestamp descending (newest first) by default. Pass order=asc to walk events chronologically — useful for reconstructing a session or building a breadcrumb timeline.
Auth required: Yes (events:read permission or JWT)
Rate limited: Yes
Query parameters
| Parameter | Type | Description |
|---|---|---|
team_id | string | Filter to a specific team. |
project_id | string | Filter to apps within a project. |
app_id | string | Filter to a specific app. |
level | string | Filter by log level: info, debug, warn, error. Accepts a single value (level=info) or a comma-separated list (level=info,warn). |
user_id | string | Filter by user ID. |
session_id | string | Filter by session ID. |
environment | string | Filter by environment: ios, ipados, macos, android, web, backend. |
screen_name | string | Filter by screen name (exact match). |
since | string | Start time. Relative (1h, 30m, 7d, 1w, 30s) or ISO 8601. |
until | string | End time. Relative (1h, 30m, 7d, 1w, 30s) or ISO 8601. |
data_mode | string | production (default), development, or all. |
cursor | string | Cursor from previous response for pagination. Tied to the current order. |
limit | number | Items per page (1-200, default 50). |
order | string | Sort direction by timestamp: desc (default, newest first) or asc (oldest first). |
Response
{
"events": [
{
"id": "uuid",
"app_id": "uuid",
"client_event_id": "uuid",
"session_id": "uuid",
"user_id": "owl_anon_abc123",
"api_key_id": "uuid",
"level": "info",
"source_module": "HomeViewController",
"message": "screen_viewed",
"screen_name": "Home",
"custom_attributes": {
"button_color": "blue"
},
"environment": "ios",
"os_version": "17.4",
"app_version": "1.2.0",
"sdk_name": "owlmetry-swift",
"sdk_version": "0.1.0",
"build_number": "42",
"device_model": "iPhone15,2",
"locale": "en_US",
"country_code": "US",
"is_dev": false,
"experiments": {
"onboarding_flow": "variant_b"
},
"timestamp": "2024-01-15T10:30:00.000Z",
"received_at": "2024-01-15T10:30:01.000Z"
}
],
"cursor": "2024-01-15T10:29:00.000Z",
"has_more": true
}When has_more is true, pass the cursor value to the next request to fetch the next page. When has_more is false, cursor is null.
GET /v1/events/count
Return aggregate counts for events matching the filters — cheaper than fetching rows when you only need totals (e.g. dashboard stats). Returns the total event count alongside the number of distinct users and sessions in the window.
Auth required: Yes (events:read permission or JWT)
Rate limited: Yes
Query parameters
Accepts the same filter parameters as GET /v1/events (except cursor, limit, and order): team_id, project_id, app_id, level, user_id, session_id, environment, screen_name, since, until, data_mode.
Response
{
"count": 1284,
"unique_users": 128,
"unique_sessions": 342
}GET /v1/events/:id
Get a single event by ID.
Auth required: Yes (events:read permission or JWT)
Response
{
"id": "uuid",
"app_id": "uuid",
"project_id": "uuid",
"client_event_id": "uuid",
"session_id": "uuid",
"user_id": "owl_anon_abc123",
"api_key_id": "uuid",
"level": "info",
"source_module": "HomeViewController",
"message": "screen_viewed",
"screen_name": "Home",
"custom_attributes": {
"button_color": "blue"
},
"environment": "ios",
"os_version": "17.4",
"app_version": "1.2.0",
"sdk_name": "owlmetry-swift",
"sdk_version": "0.1.0",
"build_number": "42",
"device_model": "iPhone15,2",
"locale": "en_US",
"country_code": "US",
"is_dev": false,
"experiments": null,
"timestamp": "2024-01-15T10:30:00.000Z",
"received_at": "2024-01-15T10:30:01.000Z",
"attachments": [
{
"id": "uuid",
"original_filename": "crash.log",
"content_type": "text/plain",
"size_bytes": 2048,
"uploaded_at": "2024-01-15T10:30:02.000Z"
}
]
}The project_id is resolved from the event's app. The attachments array contains non-deleted attachments associated with the event (empty array if none).
Returns 404 if the event does not exist or belongs to an app outside the caller's team.