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.
This endpoint backs the Affitor dashboard. It accepts only a signed-in dashboard session for a workspace member of the program and does not accept a program API key (aff_…), so you cannot call it from a server integration with your API key.
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:59ZResponse
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_typeis a normalized field added by the server:"click","lead", or"conversion".timestampis a normalized field set to the source event's native time field (click_timestamp,lead_timestamp, orsale_date).- Test events (
is_test: true) are excluded from all three tables before merging. - Each event type is read newest-first, capped at 3 ×
pageSizerows per type, then merged and paginated.totalis the size of that merged set, not the full event count: it is at most 3 ×pageSizefor one event type (9 ×pageSizefor all three), and pages beyond it come back empty even when older events exist. Narrow the window withdateFrom/dateToto reach older events.
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 |