> ## Documentation Index
> Fetch the complete documentation index at: https://docs.traceten.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Events API

> Read the most recent events for a site.

## Base URL and authentication

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

Takes `Authorization: Bearer <YOUR_API_KEY>` ([details](/api/authentication)) 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`](/api/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.

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

```json theme={null}
{
  "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](/privacy/data-collected#data-retention) for the full picture.

## Next

* [Traffic sources](/api/sources) for aggregated numbers rather than individual events