Event logs

HappyView logs system events: lexicon changes, record operations, script errors, user actions, and more. See the Event logs guide for details on event types and retention.

TypeScript

const TOKEN = "hv_..."; // your API key
const headers = { Authorization: `Bearer ${TOKEN}` };

JavaScript

const TOKEN = "hv_..."; // your API key
const headers = { Authorization: `Bearer ${TOKEN}` };

Rust

let token = "hv_..."; // your API key

Go

const token = "hv_..." // your API key

cURL

# All examples assume $TOKEN is an API key (hv_...)
AUTH="Authorization: Bearer $TOKEN"

List event logs

GET /admin/events

TypeScript

interface EventLog {
  id: string;
  event_type: string;
  severity: string;
  actor_did: string | null;
  subject: string | null;
  detail: Record<string, unknown>;
  created_at: string;
}

interface EventLogResponse {
  events: EventLog[];
  cursor?: string;
}

const response = await fetch(
  "http://127.0.0.1:3000/admin/events?severity=error&limit=10",
  { headers },
);
const data: EventLogResponse = await response.json();

JavaScript

const response = await fetch(
  "http://127.0.0.1:3000/admin/events?severity=error&limit=10",
  { headers },
);
const data = await response.json();

Rust

let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:3000/admin/events")
    .query(&[("severity", "error"), ("limit", "10")])
    .bearer_auth(token)
    .send()
    .await?;
let data: serde_json::Value = response.json().await?;

Go

req, _ := http.NewRequest("GET", "http://127.0.0.1:3000/admin/events?severity=error&limit=10", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, err := http.DefaultClient.Do(req)
if err != nil {
  log.Fatal(err)
}
defer resp.Body.Close()

cURL

curl "http://127.0.0.1:3000/admin/events?severity=error&limit=10" -H "$AUTH"

Param	Type	Required	Description
event_type	string	no	Filter by exact event type (e.g. script.error)
category	string	no	Filter by category prefix (e.g. lexicon matches every lexicon.* event). Separate several with commas to match any of them
severity	string	no	Filter by severity: info, warn, or error. Separate several with commas to match any of them
subject	string	no	Filter by subject (lexicon ID, record URI, admin DID, etc.). Matches any subject containing the value
after	string	no	Only events at or after this RFC 3339 time
before	string	no	Only events before this RFC 3339 time
cursor	string	no	Pagination cursor: the cursor from a previous response
limit	number	no	Results per page (default 50, max 100)

Response: 200 OK

{
  "events": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "event_type": "script.error",
      "severity": "error",
      "actor_did": "did:plc:abc123",
      "subject": "com.example.feed.like",
      "detail": {
        "error": "attempt to index nil value",
        "script_source": "function handle(input, ctx) ... end",
        "input": { "status": "hello" },
        "caller_did": "did:plc:abc123",
        "method": "com.example.feed.like",
        "duration_ms": 12
      },
      "created_at": "2026-03-01T12:00:00Z"
    }
  ],
  "cursor": "2026-03-01T11:59:00+00:00"
}

Events are returned in reverse chronological order (newest first). actor_did and subject are null for an event that has none. Pass the cursor value from the response to fetch the next page. A cursor comes back whenever a page is full, so the page after the last full one can be empty; a response with fewer events than limit has no cursor key. An empty parameter counts as unset, and an unreadable after or before is a 400.

Permission: events:read

Count event logs

GET /admin/events/count

Counts the events that match the same filters as List event logs: event_type, category, severity, subject, after and before. cursor and limit are ignored.

Permission: events:read

Response: 200 OK

{ "count": 1284 }

Purge event logs

POST /admin/events/purge

Deletes the events that match a filter, in a background job. The body takes the same filters as the list, all optional:

{ "category": "record", "before": "2026-09-01T00:00:00Z" }

An empty filter deletes every event

A body with no filters, {}, matches every event, and the job deletes them all.

Permission: events:purge

Response: 202 Accepted

{ "job_id": "550e8400-e29b-41d4-a716-446655440000" }

The job is a happyview.purge-event-logs job; watch it there. The purge itself is logged as an event_logs.purged event. An unreadable after or before is a 400.