List Tracking Events

Retrieve paginated, merged tracking events (clicks, leads, conversions) for a program

GET /api/tracking/events/:programId

Returns a merged, reverse-chronological list of click, lead, and conversion events recorded for the specified program. Events from all three tables are fetched, normalized to a common shape, sorted by timestamp, and then paginated.

Authentication

This endpoint uses workspace-policy enforcement. The request must carry a valid authenticated session that has been granted the tracking:list action for the program. This is enforced by the verify-program-access policy on the Strapi backend.

Path Parameter

Parameter	Type	Required	Description
`programId`	integer	Yes	Numeric ID of the affiliate program

Query Parameters

Parameter	Type	Required	Default	Description
`page`	integer	No	`1`	Page number (1-indexed)
`pageSize`	integer	No	`10`	Number of events per page
`eventType`	string	No	(all)	Filter by event type. Accepted values: `click`, `lead`, `conversion`
`dateFrom`	string (ISO 8601)	No	(none)	Inclusive lower bound on event timestamp
`dateTo`	string (ISO 8601)	No	(none)	Inclusive upper bound on event timestamp

Example request

GET /api/tracking/events/42?page=1&pageSize=10&eventType=click&dateFrom=2026-06-01T00:00:00Z&dateTo=2026-06-07T23:59:59Z

Response

Returns a data array of normalized event objects and a meta.pagination block.

Success `200`

{
  "data": [
    {
      "id": 301,
      "event_type": "click",
      "timestamp": "2026-06-07T14:22:10.000Z",
      "click_id": "cust_42_1749305730000",
      "session_id": "sess_1749305730000",
      "page_url": "https://example.com/pricing?aff=PARTNER123",
      "referrer_url": "https://twitter.com",
      "geo_country": "US",
      "geo_region": "CA",
      "geo_city": "San Francisco",
      "device_type": "desktop",
      "device_os": "macOS",
      "browser_name": "Chrome",
      "converted": false,
      "createdAt": "2026-06-07T14:22:10.512Z"
    },
    {
      "id": 87,
      "event_type": "lead",
      "timestamp": "2026-06-06T09:11:42.000Z",
      "click_id": "cust_42_1749218702000",
      "customer_key": "usr_abc123",
      "session_id": "sess_1749218702000",
      "page_url": "https://example.com/signup",
      "converted": false,
      "createdAt": "2026-06-06T09:11:42.301Z"
    },
    {
      "id": 15,
      "event_type": "conversion",
      "timestamp": "2026-06-05T16:45:00.000Z",
      "click_id": "cust_42_1749131100000",
      "amount_cents": 9900,
      "currency": "USD",
      "sale_type": "payment",
      "payment_status": "paid",
      "processor_event_id": "txn_abc123",
      "is_recurring": false,
      "createdAt": "2026-06-05T16:45:01.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 10,
      "pageCount": 3,
      "total": 28
    }
  }
}

Field notes

event_type is a normalized field added by the server: "click", "lead", or "conversion".
timestamp is a normalized field set to the source event's native time field (click_timestamp, lead_timestamp, or sale_date).
Test events (is_test: true) are excluded from all three tables before merging.
The response total reflects the merged in-memory count after applying filters, not a direct DB count.

Errors

Status	When
`404`	`programId` does not match any program
`403`	Caller does not have `tracking:list` access for the program
`500`	Unexpected server error

On this page