Events API - Traceten

Base URL and authentication

https://api.traceten.com/v1/events

Takes Authorization: Bearer <YOUR_API_KEY> (details) and the stats:read permission. site_id is the site’s snippet key, the ttid_ value your install snippet carries as data-site. You can read it from GET /v1/sites.

`GET /v1/events/recent`

The most recent events for one site, newest first. This is a live feed for checking an install or debugging a classification, not an export. It is capped at 200 events and a 90 day window.

curl "https://api.traceten.com/v1/events/recent?site_id=ttid_7Rb4TrC1dTbnD8w3s1TS12&limit=2" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

{
  "events": [
    {
      "event_id": "1f9c2b70-5a4e-4a13-9a77-0c2f4b8e1d33",
      "site_id": "ttid_7Rb4TrC1dTbnD8w3s1TS12",
      "session_id": "8a2e5c11-3f60-4b92-bb04-6d1e7a9f2c05",
      "event_ts": "2026-08-26T14:03:22Z",
      "url": "https://example.com/pricing?utm_source=chatgpt",
      "ai_source": "chatgpt",
      "ai_confidence": 0.92,
      "detection_method": "rules",
      "country_code": "US",
      "event_name": "pageview",
      "exit_domain": "",
      "source_name": "chatgpt.com",
      "device_type": "desktop",
      "browser": "chrome",
      "os": "macos"
    }
  ]
}

Query parameters

Parameter	Type	Required	Notes
`site_id`	string	yes	The snippet key.
`limit`	integer	no	1 to 200. Defaults to 50.
`days`	integer	no	1 to 90. How far back to look. Defaults to 7.

Response fields

Field	Type	Notes
`event_id`	string	Unique per event.
`site_id`	string	The snippet key you passed in.
`session_id`	string	Groups events from one visit. Pseudonymous.
`event_ts`	ISO-8601	When the event happened. Named `event_ts`, not `timestamp`.
`url`	string	The page, including its query string. See below.
`ai_source`	string	The detected source, for example `chatgpt`, `perplexity`, `direct`, `organic_search`.
`ai_confidence`	number	0 to 1. How certain the classifier is. Never a bare yes or no.
`detection_method`	string	Which detection method decided, so you can debug a classification you disagree with.
`country_code`	string	Two letter code derived from the request.
`event_name`	string	`pageview`, `click`, `exit`, `session_start` or a custom name. Empty on older events.
`exit_domain`	string	The destination host when an `exit` left for another site. Empty otherwise.
`source_name`	string	The host the visit came from, given only when the visit’s source is this event’s source.
`device_type`	string	The visit’s device: `desktop`, `mobile`, `tablet` or `bot`. Empty when unknown.
`browser`	string	The visit’s browser, such as `chrome`. Empty when unknown.
`os`	string	The visit’s operating system, such as `macos`. Empty when unknown.

What `url` contains

The query string is kept, because campaign attribution depends on it: utm_source, utm_campaign, ref and anything else you use all arrive intact. The value of any parameter whose name is a known personal-data parameter, or matches token, secret or key, is replaced with the literal string REDACTED. The parameter name itself survives. This applies to parameters in the query string and in the fragment after #, in url, the referrer and a clicked link. A hash route such as #/pricing is left as it is. The rewrite runs twice. The browser snippet applies it before sending, and our ingestion edge applies the same rule to every event it receives, including events sent straight to the ingestion API from a server SDK or your own code. The edge rewrite works on the text of the URL rather than parsing it, so a URL that does not parse is still redacted. ai_source carries non-AI values too (direct, organic_search, social, email, paid, referral), so it is a source label rather than an AI flag. Read ai_confidence and detection_method alongside it.

Errors

Status	Cause
`401`	Missing, malformed, revoked or expired key.
`403`	The key is valid but lacks `stats:read`. The body names the permission.
`404`	No such site, or the key does not cover it.
`422`	`site_id` is missing, or is neither a snippet key nor a UUID, or `limit`/`days` is out of range.
`429`	Rate limited. Back off and retry.

Retention

The store behind this endpoint keeps 90 days, so days cannot reach further back than that. That is a deliberately short window on a debugging feed, not the retention limit for your data: the underlying records are kept for 730 days and are reachable through the other endpoints below. Other records about the same activity live longer and are not reachable here: visitor step rows, which back funnel questions, are kept for 730 days, and session-level records for 730 to 760 days. Those are different tables with different retentions, not a contradiction. See data retention for the full picture.

Traffic sources for aggregated numbers rather than individual events

​Base URL and authentication

​GET /v1/events/recent

​Query parameters

​Response fields

​What url contains

​Errors

​Retention

​Next