Events API

Events are tracked interactions across all connected sources — page views, form submissions, button clicks, video plays, email opens, custom events. The tracker is the primary source, but events can also come from email integrations, CRM syncs, and track() calls.

All endpoints require events:read.

List Events

GET /v1/events

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number.
limit	number	20	Results per page (1–100).
event_type	string	—	Filter by exact event name (e.g. page_view).
contact_id	string	—	Filter to a single contact’s events.
domain	string	—	Filter by domain (host where the event was recorded).
url_contains	string	—	Filter where event URL contains this substring.
date_after	string	—	ISO 8601 — events at or after this timestamp.
date_before	string	—	ISO 8601 — events at or before this timestamp.
identified_only	boolean	false	Only include events linked to a known contact.
search	string	—	Free-text across event name, URL, domain.
sort_by	string	timestamp	One of timestamp, event, createdAt.
sort_dir	string	desc	asc or desc.
count_only	boolean	false	If true, return only { count } — no records.
fields	string	—	Set to summary for a compact projection (no enrichment).

Response — 200 OK

By default, events are enriched with the associated contact and company:

{
  "status": "success",
  "events": [
    {
      "_id": "evt_abc",
      "event": "page_view",
      "timestamp": "2026-04-29T11:23:45.000Z",
      "url": "https://example.com/pricing",
      "domain": "example.com",
      "data": { "title": "Pricing — Example", "path": "/pricing" },
      "internal_contact_id": "ct_abc",
      "contact": {
        "_id": "ct_abc",
        "email": "[email protected]",
        "firstname": "Ada",
        "lastname": "Lovelace"
      },
      "company": {
        "_id": "co_xyz",
        "name": "Analytical Engines",
        "domain": "example.com"
      }
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total_pages": 12, "total_items": 234 }
}

In fields=summary mode, each event is reduced to { id, event, timestamp, url, contact_id } — useful for high-volume listings.

---

Get Event Types

GET /v1/events/types

Returns the distinct event names recorded for the tenant. Useful for populating a filter dropdown.

Response — 200 OK

{
  "status": "success",
  "types": ["button_click", "first_visit", "form_submit", "page_view", "video_play"],
  "total_items": 5
}

---

Get Event Stats

GET /v1/events/stats

Aggregated counts, optionally grouped by type, domain, or day. Use this for dashboards instead of paginating the list endpoint.

Query Parameters

Parameter	Type	Default	Description
event_type	string	—	Filter to a single event type.
domain	string	—	Filter to a single domain.
date_after	string	—	ISO 8601 lower bound.
date_before	string	—	ISO 8601 upper bound.
identified_only	boolean	false	Only count events linked to a known contact.
group_by	string	—	One of type, domain, day. Omit for all three.

Response — 200 OK

{
  "status": "success",
  "stats": {
    "total": 12_503,
    "by_type": [
      { "type": "page_view", "count": 9_812 },
      { "type": "button_click", "count": 1_204 }
    ],
    "by_domain": [
      { "domain": "example.com", "count": 11_900 }
    ],
    "by_day": [
      { "date": "2026-04-29", "count": 432 },
      { "date": "2026-04-28", "count": 511 }
    ]
  }
}

by_day is capped at the most recent 90 days. by_type and by_domain are capped at 50 entries each.

---

Get a Single Event

GET /v1/events/:event_id

Returns the full event document, enriched with associated contact and company.

For richer aggregations across contacts, companies, or events with custom dimensions and metrics, use the Aggregate endpoint.