Events

GET /api/v1/sites/:id/events

One endpoint, four shapes. Which one you get depends on which parameters are present.

Parameters	Returns
(no `event`)	The event list
`event=…&series=1`	That event over time, plus its summary
`event=…`	Its property keys
`event=…&property=…`	That property’s values

All four accept range and every filter key.

series=1 is truthy for any value other than 0 and false. Same for histogram.

1. The event list

curl -s -H "Authorization: Bearer tk_live_…" \
  "https://tracing.tools/api/v1/sites/pk_live_a91c3f04/events?range=30d"

{
  "data": [
    {
      "name": "signup_completed",
      "type": "custom",
      "events": 412,
      "visitors": 388,
      "perVisitor": 1.0618556701030928,
      "previousEvents": 361,
      "previousVisitors": 344,
      "delta": 14.127423822714681,
      "lastSeen": "2026-09-16T16:52:09Z",
      "spark": [
        { "date": "2026-08-18T00:00:00", "value": 11 },
        { "date": "2026-08-19T00:00:00", "value": 9 }
      ]
    }
  ]
}

Field	Meaning
`type`	`custom`, `outbound` or `revenue`. A name sent as two types reports the one most of its hits used
`events` / `visitors`	Occurrences, and distinct visitors who fired it
`perVisitor`	`events / visitors`. `3.4` means people repeat it
`previousEvents` / `previousVisitors`	The same over the preceding window, or `null`
`delta`	Percentage change in volume, `null` when there is no comparison
`lastSeen`	Most recent occurrence in range
`spark`	One zero-filled point per bucket of the range

Up to 100 events, ranked by volume. Only named types appear — a plain pageview has no name.

2. One event over time

curl -s -H "Authorization: Bearer tk_live_…" \
  "https://tracing.tools/api/v1/sites/pk_live_a91c3f04/events?event=signup_completed&series=1&range=7d"

{
  "data": [
    { "date": "2026-09-10T00:00:00", "Events": 58, "Visitors": 55 },
    { "date": "2026-09-11T00:00:00", "Events": 61, "Visitors": 57 }
  ],
  "summary": {
    "name": "signup_completed",
    "type": "custom",
    "events": 412,
    "visitors": 388,
    "visitorShare": 8.063765182186235,
    "perVisitor": 1.0618556701030928,
    "sessions": 401,
    "medianPerSession": 1,
    "firstSeen": "2026-09-10T02:11:44Z",
    "lastSeen": "2026-09-16T16:52:09Z",
    "previous": {
      "events": 361,
      "visitors": 344,
      "visitorShare": 7.805763557975947,
      "perVisitor": 1.0494186046511629
    },
    "delta": {
      "events": 14.127423822714681,
      "visitors": 12.790697674418606,
      "visitorShare": 3.3053,
      "perVisitor": 1.1855
    }
  }
}

Field	Meaning
`visitorShare`	Percentage of the range’s visitors who fired it at least once
`sessions`	Distinct visits it occurred in
`medianPerSession`	Typical repeats inside one visit — a mean hides the few visits that spam

visitorShare’s denominator deliberately drops the event, propKey and propValue selections; measured against itself it would always be 100%.

3. Property keys

curl -s -H "Authorization: Bearer tk_live_…" \
  "https://tracing.tools/api/v1/sites/pk_live_a91c3f04/events?event=signup_completed"

{
  "data": [
    {
      "key": "plan",
      "events": 412,
      "values": 3,
      "dataType": "string",
      "coverage": 100,
      "numeric": null
    },
    {
      "key": "seats",
      "events": 388,
      "values": 27,
      "dataType": "number",
      "coverage": 94.17475728155339,
      "numeric": { "sum": 2104, "avg": 5.422680412371134, "min": 1, "max": 250, "p50": 3 }
    }
  ]
}

Field	Meaning
`events`	Occurrences of the event that carried the key
`values`	Distinct values, across the text, number and date columns
`dataType`	The dominant stored type: `string`, `number`, `boolean` or `date`
`coverage`	Percentage of the event’s occurrences in range that carried the key
`numeric`	`{ sum, avg, min, max, p50 }` for number keys, otherwise `null`

Up to 50 keys.

4. Property values

curl -s -H "Authorization: Bearer tk_live_…" \
  "https://tracing.tools/api/v1/sites/pk_live_a91c3f04/events?event=signup_completed&property=plan"

{
  "data": [
    { "name": "pro",        "value": 241, "events": 241, "share": 58.49514563106796 },
    { "name": "team",       "value": 118, "events": 118, "share": 28.640776699029125 },
    { "name": "enterprise", "value": 53,  "events": 53,  "share": 12.864077669902912 }
  ],
  "total": 412,
  "dataType": "string",
  "histogram": []
}

Field	Meaning
`value`	Occurrences of this value
`events`	Distinct events carrying it
`share`	`value / total × 100`
`total`	Occurrences of the key in range — the denominator behind `share`
`dataType`	The dominant stored type

A missing or empty value is reported as the literal (empty). Up to 25 values.

Histogram

Add histogram=1 on a numeric key. A number with hundreds of distinct values says nothing as a list, so it is bucketed into twelve equal-width bins instead:

curl -s -H "Authorization: Bearer tk_live_…" \
  "https://tracing.tools/api/v1/sites/pk_live_a91c3f04/events?event=signup_completed&property=seats&histogram=1"

{
  "data": [ { "name": "1", "value": 141, "events": 141, "share": 36.34 } ],
  "total": 388,
  "dataType": "number",
  "histogram": [
    { "name": "1–21.75", "value": 366, "from": 1, "to": 21.75 },
    { "name": "21.75–42.5", "value": 14, "from": 21.75, "to": 42.5 },
    { "name": "228.25–250", "value": 1, "from": 228.25, "to": 250 }
  ]
}

Both edges come off the same expression, so the top of one bin is printed as the bottom of the next. histogram is [] on a non-numeric key, or without the flag.

Errors

Status	Body
`401`	`{"error":"Missing or invalid API key"}`
`404`	`{"error":"site not found"}`

An event name that does not exist is not an error — you get an empty or zero-valued shape.