Skip to content
Pathbound DOCS
Sign in Start free →

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 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).
contact_idstring—Filter to a single contact’s events.
domainstring—Filter by domain (host where the event was recorded).
url_containsstring—Filter where event URL contains this substring.
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).
includestring—Comma-separated list of optional fields to include. Currently supports provenance to add the per-field source/timestamp record (properties_provenance).

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 Tracked events → 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.