Events API

Retrieve engagement events for the active Organizational Unit. Events represent lead actions such as page views, email opens, form submissions, and other tracked interactions.

GET /events

List all events for the active Organizational Unit with optional filtering and pagination.

Request

Parameter	Type	Required	Description
page	integer	No	Page number (default: 1)
limit	integer	No	Results per page (default: 25, max: 100)
event_type	string	No	Filter by event type (e.g., Page View, Email Open)
lead_id	string	No	Filter by specific lead
range	string	No	Date range filter: today, yesterday, last_7d, last_30d, last_90d

Response

200 OK

{
  "events": [
    {
      "id": "evt-123",
      "lead_id": "ld_456",
      "event_type": "Page View",
      "metadata": {
        "path": "/pricing",
        "referrer": "https://google.com"
      },
      "created_at": "2025-01-15T10:30:00Z"
    },
    {
      "id": "evt-124",
      "lead_id": "ld_789",
      "event_type": "Email Open",
      "metadata": {
        "campaign": "Q1 Nurture"
      },
      "created_at": "2025-01-15T10:25:00Z"
    }
  ],
  "total": 150,
  "page": 1,
  "limit": 25
}

Response Fields

Field	Type	Description
id	string	Unique event identifier
lead_id	string	Lead who performed the action
event_type	string	Type of action (e.g., Page View, Form Submit)
metadata	object	Additional context about the event
suppression_reason	string or null	Why this event was excluded from scoring. null means the event scored normally. See Suppression Reasons
original_lead_id	string or null	If this event was moved during a lead merge, the ID of the lead that originally owned it. null for events that were never moved
created_at	timestamp	When the event occurred

Suppression Reasons

When an event is excluded from scoring, the suppression_reason field explains why:

Value	Meaning
null	Event scored normally — not suppressed
"inorganic"	Suppressed by a velocity based filter (event exceeded the rate threshold)
"inorganic_grouped"	Part of a velocity burst where Keep First, Suppress Rest is enabled — this was not the first event in the burst
"metadata_filter"	Suppressed by an attribute based filter (event metadata matched a key/value condition)

Suppressed events are stored in kenbun for audit purposes but do not contribute to lead scores, session creation, or lead creation.

Example

curl -X GET "https://api.kenbun.io/events?page=1&limit=25&event_type=Page%20View" \
  -H "Authorization: Bearer <token>"

Common Errors

Status	Meaning	Solution
401	Unauthorized	Check authentication token
500	Server Error	Contact support if persists

---

DELETE /events/batch

Delete multiple events by ID. This action cannot be undone.

Request Body

{
  "event_ids": ["evt-123", "evt-124", "evt-125"]
}

Response

200 OK

Common Errors

Status	Meaning	Solution
400	Bad Request	Provide a valid array of event IDs
401	Unauthorized	Check authentication token

---

Notes

• Events are OU-scoped and only return data for the active Organizational Unit
• Events are created automatically when data is ingested via the /ingest endpoint
• Use event type filters to focus on specific engagement signals
• For real-time event streaming, see the Stream endpoint

Related Endpoints

• Events for a Lead - View events for a specific lead
• Event Export - Export events as CSV
• Event Analytics - Aggregated event data
• Event Ingestion - Send events to kenbun