> ## 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. # Stats API > Headline numbers for a site: totals, a bucketed series, live activity, and site metadata. ## Base URL and authentication ``` https://api.traceten.com/v1/stats ``` Takes `Authorization: Bearer ` ([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). Every response uses the standard envelope: `{"status": "success", "data": ...}`. Errors are described in [Errors](/api/errors). ## `GET /v1/stats/overview` Every headline number for one window, including the share of traffic that came from AI assistants. These are the same figures the dashboard Overview shows, computed by the same query, so the two always agree. ```bash theme={null} curl "https://api.traceten.com/v1/stats/overview?site_id=ttid_7Rb4TrC1dTbnD8w3s1TS12&from=2026-08-01&to=2026-08-07" \ -H "Authorization: Bearer " ``` ```json theme={null} { "status": "success", "data": { "site_id": "ttid_7Rb4TrC1dTbnD8w3s1TS12", "from": "2026-08-01", "to": "2026-08-07", "timezone": "UTC", "visitors": 4821, "new_visitors": 3190, "sessions": 6104, "pageviews": 19338, "conversions": 142, "conversion_rate": 0.0295, "revenue_usd_cents": 812400, "revenue_display": 8124.0, "sessions_started": 6002, "bounce_rate": 0.0841, "avg_active_time_sec": 61.4, "ai_sessions": 1877, "ai_visitors": 1502, "ai_session_share": 0.3075, "ai_visitor_share": 0.3116, "currency": "USD", "converted": false } } ``` ### Parameters | Parameter | Type | Required | Notes | | ---------- | ------ | -------- | -------------------------------------------------- | | `site_id` | string | yes | The snippet key. | | `from` | string | no | `YYYY-MM-DD`, inclusive. Must be sent with `to`. | | `to` | string | no | `YYYY-MM-DD`, inclusive. Must be sent with `from`. | | `timezone` | string | no | Must be `UTC`. See [Time zones](#time-zones). | | `fields` | string | no | Comma-separated field names, to trim the response. | Send `from` and `to` together or send neither. A half-open range is a `422`, because "from August 1st to whenever the server thinks now is" is a different question from the one you asked and the answer is not reproducible. With neither, the window is the last 7 days including today. A range may not span more than 731 days. ### Response fields | Field | Notes | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `visitors` | Distinct browsers, not people. One person on a phone and a laptop is two. | | `new_visitors` | Visitors whose first ever visit fell inside this window. Returning visitors are `visitors - new_visitors`. | | `sessions` | Sessions active in the window. | | `pageviews` | Pageview events only. Exits, session starts and custom events are not counted. | | `conversions` | Visitors who completed any goal or made a payment, across all traffic. Each visitor counts once, and a refunded payment still counts. `null` when the window starts more than 365 days ago, because goal and payment records are kept for 365 days. | | `conversion_rate` | `conversions / visitors`, 0.0 to 1.0. The dashboard Overview's Conversion %. `null` when there were no visitors or `conversions` is `null`. | | `revenue_usd_cents` | Attributed revenue in whole US cents. Storage is always USD. | | `revenue_display` | The same revenue in your site's currency, converted at each day's rate. `null` if any day had no rate. | | `sessions_started` | Sessions that started in the window. The denominator for the two metrics below. | | `bounce_rate` | 0.0 to 1.0. | | `avg_active_time_sec` | Average foreground seconds per session. See [Active time is not session duration](#active-time). | | `ai_sessions` | Sessions whose source was an AI assistant. | | `ai_visitors` | Visitors who arrived from an AI assistant at least once. | | `ai_session_share` | `ai_sessions / sessions`, 0.0 to 1.0. `null` when there were no sessions. | | `ai_visitor_share` | `ai_visitors / visitors`. `null` when there were no visitors. | | `currency` | Your site's display currency. | | `converted` | `false` when your currency is USD and nothing was converted. | `missing_rate_dates` appears only when some revenue was left out of `revenue_display` because no exchange rate was published for that day. Its presence means the display total is incomplete. See [Currencies](/integrations/currencies). `bounce_rate`, `avg_active_time_sec` and `sessions_started` are `null`, not `0`, when your window reaches past the session-record retention boundary. Traceten keeps individual session records for **at least 730 days and at most 760 days** (deletion runs on monthly storage partitions, so the exact expiry for a given session falls between those bounds, see [Data retention](/privacy/data-collected#data-retention)). Beyond that these three are unknown rather than zero. Render a `null` as a dash, never as 0%. ### Active time `avg_active_time_sec` measures time your page was in the **foreground**, not the gap between a visitor's first and last event. A tab left open in the background contributes nothing. Label it "average active time" in your own interface. Calling it session duration overstates engagement. It also has no history before mid-2026: sessions recorded before active time was measured report 0, so a 0 can mean "not measured" rather than "not engaged". ## `GET /v1/stats/timeseries` The same metric block as `/overview`, one row per bucket. ```bash theme={null} curl "https://api.traceten.com/v1/stats/timeseries?site_id=ttid_7Rb4TrC1dTbnD8w3s1TS12&from=2026-08-01&to=2026-08-07&granularity=day" \ -H "Authorization: Bearer " ``` ```json theme={null} { "status": "success", "data": { "site_id": "ttid_7Rb4TrC1dTbnD8w3s1TS12", "from": "2026-08-01", "to": "2026-08-07", "timezone": "UTC", "granularity": "day", "currency": "USD", "converted": false, "buckets": [ { "bucket_start": "2026-08-01T00:00:00Z", "date": "2026-08-01", "visitors": 702, "sessions": 870, "pageviews": 2761, "conversions": 21, "revenue_usd_cents": 118200, "revenue_display": 1182.0, "ai_sessions": 268, "ai_session_share": 0.308 } ] } } ``` | Parameter | Type | Required | Notes | | ------------- | ------ | -------- | -------------------------- | | `granularity` | string | no | `day` (default) or `week`. | Everything else matches `/overview`. **Key each bucket on `bucket_start`, not `date`.** At `granularity=week`, `date` is the Monday the week starts on. **Do not add the buckets together to get a window total.** `visitors`, `sessions` and `conversions` are distinct counts, so a visitor active on three days appears in three buckets and the sum double counts them. Ask `/v1/stats/overview` for the total; it is computed across the whole window in one pass. Buckets with no traffic are **absent**, not returned as zero. You know which window you asked for, so you can fill the gaps; we will not invent a row for a day the data never saw. ### Why there is no hourly or monthly option `granularity=hour` and `granularity=month` return `422`. Hourly buckets would have to be computed from raw event records rather than from a pre-aggregated rollup. That is a much more expensive query, and this API does not run those. Hourly resolution is available in the dashboard for windows up to a week. Monthly buckets do not exist as a rollup, and building one by adding up daily buckets would over count every returning visitor, for the reason in the warning above. If you need months, ask for `day` and group them yourself using visitor counts you are willing to treat as approximate, or ask for a single month as one `/overview` call, which is exact. ## Time zones `timezone` must be `UTC`. Any other value returns `422`. Traceten stores these rollups by UTC calendar day. Accepting `timezone=Asia/Tokyo` and then returning UTC day boundaries would give you a number that looks right and is not, so the API refuses instead. If you need local days, request daily buckets from `/v1/stats/timeseries` and re-bucket them yourself. ## `GET /v1/stats/realtime` Sessions with activity in the last few minutes. ```bash theme={null} curl "https://api.traceten.com/v1/stats/realtime?site_id=ttid_7Rb4TrC1dTbnD8w3s1TS12&minutes=5" \ -H "Authorization: Bearer " ``` ```json theme={null} { "status": "success", "data": { "site_id": "ttid_7Rb4TrC1dTbnD8w3s1TS12", "window_minutes": 5, "active_sessions": 37, "last_event_at": "2026-08-27T14:22:08Z" } } ``` | Parameter | Type | Required | Notes | | --------- | ------- | -------- | ----------------------- | | `minutes` | integer | no | 1 to 60. Defaults to 5. | `active_sessions` counts **sessions, not visitors**. The live-activity records Traceten keeps carry a session identifier and no visitor identifier, so a visitor count is not available here and we do not estimate one. Two tabs open by one person can be two sessions. `last_event_at` is `null` when nothing arrived in the window. ## `GET /v1/stats/metadata` Your site's display settings. No analytics data, so this is a cheap call to make before the others. ```bash theme={null} curl "https://api.traceten.com/v1/stats/metadata?site_id=ttid_7Rb4TrC1dTbnD8w3s1TS12" \ -H "Authorization: Bearer " ``` ```json theme={null} { "status": "success", "data": { "site_id": "ttid_7Rb4TrC1dTbnD8w3s1TS12", "domain": "example.com", "name": "Example Store", "currency": "USD", "plan": "growth", "region": "us", "created_at": "2026-03-14T09:12:00.000Z", "default_timezone": "UTC" } } ``` | Field | Notes | | ------------------ | ------------------------------------------------------------------- | | `name` | Your display name for the site, or the domain if you never set one. | | `currency` | The currency revenue figures are converted into for display. | | `plan` | The plan on the account that owns this site. | | `region` | The region recorded for this site. See the note below. | | `default_timezone` | Always `UTC`. See below. | `region` is the region **recorded** for this site. It is a stored preference, not a routing guarantee: Traceten runs a single analytics cluster today and has no per-region routing, so this value does not tell you where the data physically sits. `default_timezone` is the time zone **this API** interprets date ranges in. It is not a site setting: Traceten has no per-site time zone, and there is nothing to configure. The field is here so a client can label a chart axis honestly rather than guessing. ## Errors Beyond the [standard errors](/api/errors): | Status | When | | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `422` | A half-open date range, a range over 731 days, a non-UTC `timezone`, `granularity=hour` or `month`, an unknown field in `fields`, or an unrecognised query parameter. | An unrecognised query parameter is rejected rather than ignored. A silently dropped filter would give you the wrong number with a `200` beside it, and nothing would look broken. ## Next * [Breakdowns API](/api/breakdowns) for the same traffic split by page, source, country, device and more. * [Sources API](/api/sources) for the per-source, per-day series behind the Sources page.