Skip to content
Pathbound DOCS
Sign in Start free →

Events REST API

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

All endpoints require events:read.

List Events

Section titled “List Events”
GET /v1/events

Query Parameters

Section titled “Query Parameters”
ParameterTypeDefaultDescription
pagenumber1Page number.
limitnumber20Results per page (1–100).
event_typestring—Filter by exact event name (e.g. page_view).
event_typesstring—Comma-separated event names — matches any of them (e.g. button_click,link_click).
contact_idstring—Filter to a single contact’s events.
visitor_idstring—Filter to a single anonymous visitor (includes unidentified events).
session_idstring—Filter to a single session.
domainstring—Filter by domain (host where the event was recorded).
url_containsstring—Filter where event URL contains this substring.
textstring—Exact match on the interacted element’s text/label (data.text), e.g. a button label like Go!. Safe for values containing $.
text_containsstring—Substring match on the element text/label (data.text).
titlestring—Exact match on the page title (data.title).
title_containsstring—Substring match on the page title (data.title).
element_typestring—Filter by interacted element type (data.elementType, e.g. button, a).
element_idstring—Exact match on the DOM element id (data.id).
class_containsstring—Substring match on the element CSS class (data.class). The way to target elements that have no text or id (icon buttons, etc.) — use a stable class token like MuiIconButton-root, not a hashed one (css-*, jss*).
referring_domainstring—Filter by referring domain.
device_typestring—Filter by device type (e.g. Desktop, Mobile).
browserstring—Filter by browser (e.g. Chrome).
osstring—Filter by operating system (e.g. Windows).
is_botboolean—true → only bot/crawler traffic; false → only human traffic (matches events with no is_bot flag). Omit for both.
date_afterstring—ISO 8601 — events at or after this timestamp.
date_beforestring—ISO 8601 — events at or before this timestamp.
identified_onlybooleanfalseOnly include events linked to a known contact.
searchstring—Free-text across event name, URL, domain.
sort_bystringtimestampOne of timestamp, event, createdAt.
sort_dirstringdescasc or desc.
count_onlybooleanfalseIf true, return only { count } — no records.
fieldsstring—Set to summary for a compact projection (no enrichment); summary rows include text.
includestring—Comma-separated list of optional fields to include. Currently supports provenance to add the per-field source/timestamp record (properties_provenance).

The text, title, element_type, element_id, and class_contains filters match fields inside each event’s data payload — see Event types for which event types carry them (e.g. button_click and link_click carry text/class/id/elementType). Exact-match filters (text, title, element_id, …) are literal equality, so labels containing $ or . work; *_contains filters are case-insensitive substring matches.

To count events by a payload value (e.g. how many Go! button clicks) or to count distinct visitors/contacts, prefer POST /v1/aggregate — it returns distinct_groups in one call instead of paginating here.

Response — 200 OK

Section titled “Response — 200 OK”

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

{
  "status": "success",
  "events": [
    {
      "event_id": "evt_abc",
      "_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" },
      "referring_domain": "google.com",
      "browser": "Chrome",
      "browser_version": "120",
      "os": "Mac OS X",
      "device_type": "Desktop",
      "contact": {
        "contact_id": "ct_abc",
        "_id": "ct_abc",
        "email": "[email protected]",
        "firstname": "Ada",
        "lastname": "Lovelace"
      },
      "company": {
        "company_id": "co_xyz",
        "_id": "co_xyz",
        "name": "Analytical Engines",
        "domain": "example.com"
      }
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total_pages": 12, "total_items": 234 }
}

_id is a transitional alias for event_id (and the equivalent on the embedded contact / company) and will be removed in a future release — prefer the namespaced identifier in new integrations. Internal fields (tenant_id, user_id, __v, internal_contact_id, properties_provenance) are stripped by default.

Each event also carries the server-derived fields browser, browser_version, os, device_type, and referring_domain (computed from userAgent / referrer), plus is_bot — present and true only when the request matched a known bot/crawler (bot traffic is flagged, not dropped; absent on human traffic). See Event types → Server-added fields.

In fields=summary mode, each event is reduced to { id, event, timestamp, url, contact_id } — useful for high-volume listings. The summary projection intentionally uses id (not event_id) to stay compact; the enriched contact / company are omitted entirely.

Get Event Types

Section titled “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

Section titled “Response — 200 OK”
{
  "status": "success",
  "types": ["button_click", "first_visit", "form_submit", "page_view", "video_play"],
  "total_items": 5
}

Get Event Stats

Section titled “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

Section titled “Query Parameters”
ParameterTypeDefaultDescription
event_typestring—Filter to a single event type.
domainstring—Filter to a single domain.
date_afterstring—ISO 8601 lower bound.
date_beforestring—ISO 8601 upper bound.
identified_onlybooleanfalseOnly count events linked to a known contact.
group_bystring—One of type, domain, day. Omit for all three.

Response — 200 OK

Section titled “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

Section titled “Get a Single Event”
GET /v1/events/:event_id

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

Response — 200 OK

Section titled “Response — 200 OK”
{
  "status": "success",
  "event": {
    "event_id": "evt_abc",
    "_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" },
    "referring_domain": "google.com",
    "browser": "Chrome",
    "browser_version": "120",
    "os": "Mac OS X",
    "device_type": "Desktop",
    "contact": {
      "contact_id": "ct_abc",
      "_id": "ct_abc",
      "email": "[email protected]",
      "firstname": "Ada",
      "lastname": "Lovelace"
    },
    "company": {
      "company_id": "co_xyz",
      "_id": "co_xyz",
      "name": "Analytical Engines",
      "domain": "example.com"
    }
  }
}

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