Stats API - Traceten

Base URL and authentication

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

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. Every response uses the standard envelope: {"status": "success", "data": ...}. Errors are described in 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.

curl "https://api.traceten.com/v1/stats/overview?site_id=ttid_7Rb4TrC1dTbnD8w3s1TS12&from=2026-08-01&to=2026-08-07" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

{
  "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.
`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.
`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.

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). 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.

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 <YOUR_API_KEY>"

{
  "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.

curl "https://api.traceten.com/v1/stats/realtime?site_id=ttid_7Rb4TrC1dTbnD8w3s1TS12&minutes=5" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

{
  "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.

curl "https://api.traceten.com/v1/stats/metadata?site_id=ttid_7Rb4TrC1dTbnD8w3s1TS12" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

{
  "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:

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.

Breakdowns API for the same traffic split by page, source, country, device and more.
Sources API for the per-source, per-day series behind the Sources page.

​Base URL and authentication

​GET /v1/stats/overview

​Parameters

​Response fields

​Active time

​GET /v1/stats/timeseries

​Why there is no hourly or monthly option

​Time zones

​GET /v1/stats/realtime

​GET /v1/stats/metadata

​Errors

​Next

Base URL and authentication

`GET /v1/stats/overview`

Parameters

Response fields

Active time

`GET /v1/stats/timeseries`

Why there is no hourly or monthly option

Time zones

`GET /v1/stats/realtime`

`GET /v1/stats/metadata`

Errors

Next