Querying events

This page covers reading data back out of Tidings programmatically — for exports, scheduled reports, or your own tooling. Everything you send is readable over the API, the same data the explorer, dashboards, and user profiles are built on. Note that querying uses a different credential from ingestion.

A different auth

Ingestion uses the X-API-Key key (see Authentication). The read API is different: it authenticates as a logged-in user with a token in the Authorization header — Authorization: Token <key>. Don't send an ingestion key here; the two schemes are separate.

Personal access tokens

The login token above is the one your browser session uses. For anything that is not a browser — a script, a scheduled report, a CI job, an AI agent — create a personal access token instead, under Account → Personal access tokens in the app. Tokens are prefixed tk_, shown once and hashed at rest, can carry an expiry date, and are revocable one at a time. They travel in the same header under a different scheme:

request headerhttp
Authorization: Bearer tk_your_token

A token can be limited to certain projects — it then reads only those, and none of the organization-wide routes — and it is read-only unless it carries write grants. Over this REST API the only writes are creating annotations, with the annotations grant, and creating and editing alerts, with the alerts grant; segments, saved insights, and dashboard tiles are written only through the MCP server, each with its own grant. No token can create API keys, invite members, create projects, or delete anything, which is the point: a token you leave on a build server is a narrower thing to lose than a login. Prefer one over the login token whenever the credential will outlive the sitting you created it in, and give each consumer its own so revoking one does not sign you out everywhere.

The same token is what connects an AI agent to your data over MCP — see Connect AI agents.

Endpoints

All paths are under /api/v1/ and scoped to a project you belong to. A project is addressed by its organization slug and its own slug — both are in the URL you see in the app, and GET /api/v1/projects/ lists them. Below, PROJECT stands for organizations/{org_slug}/projects/{project_slug}.

GET PROJECT/events/

List events, newest first, 50 per page. Filters: name, distinct_id, search, start, end, and filters: a JSON list of up to five {"key", "operator", "value"} objects, e.g. filters=[{"key":"plan","operator":"eq","value":"pro"}]. Operators: eq (the default), ne, gt, gte, lt, lte, contains, not_contains, is_set and is_not_set (the last two take no value). The legacy repeated prop=key:value form still works as a string-equality filter.

GET PROJECT/events/names/

The distinct event names seen in the project — the vocabulary for filtering.

GET PROJECT/events/properties/

Property keys in use; properties/{key}/values/ lists the values for one key.

GET PROJECT/events/live/?after_id={id}

Tail new events since a cursor — powers the live feed.

GET PROJECT/events/{event_id}/

A single event by id.

GET PROJECT/users/

Distinct users (by distinct_id); users/{distinct_id}/ returns one user's history.

Sessions

A session is one person's run of events with no gap longer than 30 minutes — the same rule the explorer, paths, and the charts all use, echoed back as gap_minutes. Visits are built from the events that survive your filters, not from the visit that contained them: filter to name=checkout and a session is that person's run of checkouts. Two endpoints read them — one lists the visits, one counts them.

GET PROJECT/events/sessions/

The explorer's rows, grouped into visits — the same filters as events/ (name, distinct_id, search, start, end, prop), but paged by session: page and page_size (20 by default, 50 at most). An unqualified request reads the last 7 days. Sessions come newest first, each with started_at, ended_at, duration_seconds, event_count and its events inline (up to 200, past which the session says truncated). The properties every event of a visit shares are lifted once into constant_properties — the build, the device, the release channel — and the events keep only what actually varied from step to step.

GET PROJECT/analytics/sessions/

The same visits, counted. Takes the charts' range parameters (days and interval, or start/end; 30 days by default) plus a saved segment and JSON filters, which pick the events to sessionise. Returns a summary (sessions, users, sessions per user, median and average duration, bounce rate, events per session), a series of the same numbers per bucket, and a distribution of session lengths across seven bins. The equivalent previous period comes back as previous unless you send compare=false (or the range reaches past your retention, where a comparison would quietly be a lie).

Two definitions to know before you plot any of it. The headline duration is the median_seconds, with avg_seconds reported alongside rather than in its place: session length is a skewed distribution, and one abandoned tab open all afternoon moves the average and not the median. And a one-event session has no span at all, so it is left out of both durations and out of the distribution — counted instead as bounces and reported as bounce_rate. Sessions are placed in a bucket by the time they started, and a visit already under way when the window opens begins at that edge.

Past 500,000 events in the window the answer is sampled — by user hash, one user in ten, kept whole so that no session is cut in half and no bucket of the series is emptied. The payload says so with sampled: true and sample_rate: 0.1. The counts (sessions, users, bounces, the distribution) are scaled back up by that factor and are therefore estimates; the medians, averages and rates are not scaled, because sampling whole people does not change what a typical visit looks like.

Funnels

A funnel counts the people who did an ordered sequence of events. Each person enters at their first step-0 event in the window and converts within window_days of it (14 by default, 1–90).

A breakdown is read off each person's step-0 event by default. When the property only exists on a later step — a product on purchase_completed after paywall_shown — pass breakdown_step (0-based) and the value is read off the event that step matched. Anyone who never reached that step has no value and is grouped as (not set), so for the steps before it that group also holds everyone who dropped off on the way; the response's breakdown.step says which step was read.

The top breakdown_limit values by step-0 users (5 by default, 5–20) keep their own group and the rest fold intoOther. Beyond them, up to five valuesfirst seen in the window keep a group too, flaggednew: true — first seen meaning the breakdown step's event never carried that value before the window started.breakdown.new_known is false when the window starts at or before the project's retention horizon: nothing before it is left to compare with, so nothing is flagged.breakdown_sort arranges the kept groups —auto (the default) is by users, except values that all look like versions (1.9, 1.10, v2.3.1), which come back in version order, newest first; count is always by users; value is natural ascending order, digits compared as numbers. breakdown.sort_applied says which order you got:count, value or version (the newest-first version order).

GET PROJECT/analytics/funnel/

Two to five repeated step parameters, plus the range parameters (days or start/end), window_days, ordering (loose, the default: the next step happens any time after the previous one; strict: it is the very next event the person sent), JSON filters, a saved segment and a breakdown property read off the step-0 event (with breakdown_step, breakdown_limit andbreakdown_sort; each value is{"value", "users": [n0, …], "new"}). Returns steps, each with users, conversion_from_previous, conversion_from_start and the median time to convert.

GET PROJECT/analytics/funnel/?…&over_time=day|week

Conversion over time. Adds a series: one row per day or week of the window, zero-filled, each {"date", "users": [n0, n1, …], "conversion", "conversion_steps": [null, n1/n0, n2/n1, …]}. People are grouped by the bucket they entered in, so a point is “of everyone who started on this day, how many got to each step” — conversions that happen later still count for the day they started, and the points add up to steps. Rates are fractions from 0 to 1, conversion is last step over first, and a rate is null when nobody entered. The response's interval is the unit the series used; a daily series longer than 120 points comes back weekly. With a breakdown the series is of the totals only. Recent points have had less time to convert than older ones — read the right edge with that in mind.

GET PROJECT/analytics/funnel/users/

The people behind one number: the funnel's parameters plus at (a step index) and state (converted or dropped), paged. To list the people behind one point of a series, pass entered (the point's date) with its over_time unit — not a window cut to that day, which would also cut off everyone who converted after it.

Heatmaps

Where people clicked on a page and how far down it they got, built from the $click and $scroll events the browser snippet records when heatmap capture is on. All of these take the charts' range parameters (days, or start/end; 30 days by default).

GET PROJECT/analytics/heatmap/pages/

The pages worth looking at: up to 50 (host, path) pairs ranked by clicks, each with its clicks, pageviews and scroll_samples. An activity block comes alongside them — page views in the window, the hosts they came from, the newest one's timestamp, and how many of them the browser snippet sent — so an empty list can tell no traffic from no capture.

GET PROJECT/analytics/heatmap/?path=&host=&device=

One page's heatmap. path is required — there is no heatmap of a project — host is optional and means any host, and device is all (the default), desktop, tablet or mobile. Returns a grid of [col, row, count] cells — 40 proportional columns across, 25-pixel rows down, because x is a fraction of the page width and y is a page pixel. Each click is re-anchored into the reference box the answer reports as width_px/height_px (and names in reference) before it is bucketed: sideways from the centre of the page, scaled by dw over that box, and downwards by the height ratio. Also returns the 25 most-clicked elements with their share, and a scroll curve of the share of views that reached each tenth of the page, with avg_dwell_ms.

GET PROJECT/analytics/heatmap/snapshots/?path=&host=

The status of the screenshot behind the heatmap, one entry per device (captured_at, requested_at, width, height, error), null where nothing has been asked for yet.

POST PROJECT/analytics/heatmap/snapshots/

{ path, host, device } asks for a capture, or re-asks for one that already exists; 202 with the row's status, since the screenshot itself is taken by a background job within the next few minutes. Only https pages on a host your own visitors have reported page views from can be captured.

GET PROJECT/analytics/heatmap/snapshot/?path=&host=&device=

The screenshot itself, as image/jpeg; 404 until the first capture lands.

POST PROJECT/analytics/heatmap/overlay-token/

{ path, host, device } plus the range, and back comes { token, url, expires_in } — a ten-minute link that opens your own page with the heatmap painted over it, for the screens a screenshot can never reach.

Two things to know about the numbers. Each query reads the newest 200,000 clicks on that page and says so with sampled: true when it hit the cap — a picture of the last 200,000 clicks is the same picture as one of all of them, because the question is where clicks land and not how many there were. And the device bands are read off the viewport width the browser reported (vw), not off a user agent: mobile under 768 pixels, tablet 768 to 1024, desktop from 1024 — the layout a click landed on is a function of the viewport, which is the thing that was measured. pageviews is counted from real page_view events, so clicks per view stays honest on a site that switched capture on halfway through the window.

Dashboard data

A dashboard's tiles are computed together, over one range, by one read. Two optional parameters narrow every tile at once without editing any of them: filters, a JSON list in the explorer's vocabulary above (at most five, ANDed after each tile's own filters, and on a funnel tile applied to every step), and segment, a saved segment's id (intersected with a tile's own segment, so both must hold). Like the range, they are part of the read, never saved on the dashboard. The response echoes them as "scope": {"filters": […], "segment": "<id>" | null}.

GET PROJECT/dashboard/data/

Every tile's data. Takes the range (days or start/end), filters and segment; an unknown segment is a 400.

GET organizations/{org_slug}/dashboard/data/

The organization dashboard: the same range and filters. A segment belongs to one project, so segment is a 400 here.

A tile may pin its own range with a stored range, one of {"days": 1|7|30|90}, {"start": "YYYY-MM-DD", "end": "YYYY-MM-DD"} (half-open: end is the first day not shown; at most 365 days), {"since": "YYYY-MM-DD"} or {"since_annotation": "<id>"} — the last two run to the end of the range the dashboard is read at. Such a tile is computed, compared and projected over its own window; everything else about it still applies. The annotation is not checked when the tile is saved, so deleting it turns the tile into an error rather than refusing a save. Every tile's data echoes the window it read:

tile windowjson
"window": {
  "days": 30, "interval": "day",
  "start": "2026-10-06T00:00:00+00:00", "end": "2026-11-04T09:12:00+00:00",
  "source": "tile",          // "dashboard" for a tile without a range
  "label": "Last 30 days"    // "Since 1 Nov 2026", "Since v2 shipped", "1–14 Oct 2026"
}

A breakdown tile, and a timeseries tile with abreakdown, take top_n (5–20: how many values keep their own row or line — 10 rows by default on a breakdown tile, 5 lines on a timeseries) and sort (auto,count or value, as a funnel'sbreakdown_sort: by count, except version-like values in version order, newest first). The values are always chosenby count; the sort only arranges them, and the data echoessort_applied (count, value for natural ascending, or version for newest-first version order). A value whose first occurrence — for that property, in the tile's event and filters — is inside the range is new: a breakdown tile's rows are{"name", "count", "new"}, and a timeseries keeps itsseries_keys and lists the new ones inseries_new. Up to five new values that ranked below the top are added anyway, as extra rows or extra series, and leaveOther. new_known is false when the range starts at or before the retention horizon — then nothing is flagged. The project overview's ?breakdown= series takes the sametop_n and sort and answers series_new,new_known and sort_applied besideseries_keys.

A ratio tile is one rate: anumerator over a denominator, each {event_name, filters, measure} and counted exactly as a stat tile of those would be; the tile's own filters and segment, and the dashboard's, apply to both sides. Its data is a fraction, never pre-formatted — format (percent or ratio) is how to print it — and value is null when the denominator is zero, as is a bucket's count:

ratio tilejson
{
  "type": "ratio", "format": "percent",
  "value": 0.42,
  "numerator": {"event_name": "trial_started", "measure": "users", "filters": [], "count": 84},
  "denominator": {"event_name": "paywall_shown", "measure": "users", "filters": [], "count": 200},
  "series": [{"date": "2026-11-03", "count": 0.4, "numerator": 12, "denominator": 30}, …],
  "previous": {"value": 0.38, "numerator": 76, "denominator": 200} | null
}

previous is filled only when the tile asks to compare and the previous window is wholly inside retention.

Annotations

An annotation is a dated note pinned to a project's timeline — it shows up as a marker on the charts covering that day, so a spike arrives with its explanation attached. The obvious use is a deploy marker: have your release pipeline POST one when it ships.

terminalbash
$ curl -X POST $TIDINGS_API/api/v1/organizations/<org>/projects/<project>/annotations/ \
    -H 'Authorization: Token <your token>' \
    -H 'Content-Type: application/json' \
    -d '{"date": "2026-09-15", "text": "v1.5 shipped"}'

A user token, not an ingestion key — annotations are written by your team, not by your app. date is a day, not a timestamp, and text is at most 200 characters. GET PROJECT/annotations/ lists them, narrowed by the same days or start/end range as the charts, and GET organizations/{org_slug}/annotations/ merges every project in the organization.

Alerts

An alert watches one number — a stat or ratio tile, in the dashboard's own vocabulary — over the last hour, 6 hours, day or week, and tells you when it crosses a line (gt, gte, lt, lte, or change_down_pct / change_up_pct against the period before) or leaves its usual range (anomaly: more than 2, 3 or 4 standard deviations from the same period over the previous 14). Alerts are evaluated every five minutes; a fire and a recovery are each notified once, by email to members of the organization and to an https webhook. "Crash > 0 in the last hour":

terminalbash
$ curl -X POST $TIDINGS_API/api/v1/organizations/<org>/projects/<project>/alerts/ \
    -H 'Authorization: Bearer tk_your_token' \
    -H 'Content-Type: application/json' \
    -d '{"name": "Crashes", "query": {"type": "stat", "event_name": "crash"}, "period": 60, "kind": "threshold", "condition": "gt", "threshold": 0, "webhook_url": "https://example.com/hooks/tidings"}'

GET/POST PROJECT/alerts/, GET/PATCH/DELETE PROJECT/alerts/{id}/, POST PROJECT/alerts/{id}/test/ (evaluate now and send a test on every channel, 10 an hour) and GET PROJECT/alerts/{id}/events/ (the last 50 fires, recoveries and tests, with each channel's delivery result). A personal access token needs the alerts grant to create or edit one and can never delete one. A ratio's value is a fraction, so its threshold is too (0.2 is 20%). The webhook_secret is in the response that set the webhook and never again; PATCH {"rotate_webhook_secret": true} issues a new one, once.

Each webhook is a JSON POST with X-Tidings-Event (alert.fired, alert.recovered or alert.test) and X-Tidings-Signature: sha256= and the hex HMAC-SHA256 of the raw body, keyed with the secret. It must answer 2xx within 5 seconds; it is not retried, and redirects are not followed.

webhook bodyjson
{
  "id": "5f0c…", "type": "alert.fired", "event_id": "1b9e…",
  "alert": {"id": "…", "name": "Crashes", "project": "harborlight/web", "kind": "threshold",
            "query": {"type": "stat", "event_name": "crash", …}, "period": 60,
            "condition": "gt", "threshold": 0, "description": "crash > 0 in the last hour", …},
  "state": "firing", "value": 3, "previous": 0,
  "window": {"start": "2026-11-04T09:05:00+00:00", "end": "2026-11-04T10:05:00+00:00"},
  "fired_at": "2026-11-04T10:05:00+00:00"
}
verify (Python)python
import hashlib, hmac

def verified(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

Verify against the bytes you received, before parsing them. A project's dashboard can also mail its KPI row — its stat and ratio tiles, yesterday against the day before — once a day: GET/PUT PROJECT/dashboard/digest/ with {enabled, hour_utc, emails}.

Internal users

Your own phone tapping through the paywall on launch day is not demand. Mark the team's devices and test accounts as internal identities — by distinct_id, or by a property match such as install_id = … for a device that has no stable id yet — and their events drop out of every aggregate: overviews, funnels (named steps included), retention, paths, sessions, the Users list, segments, dashboards, heatmaps and the schema. A property value matches as the string you typed and as the number or boolean it spells, so an id sent as 42 and as "42" are both caught.

Add ?include_internal=1 to any analytics, Users or dashboard read to count them again. Those responses echo "internal": {"excluded": true} when something was left out — overview, funnel, retention, paths, sessions, the Users list and dashboard data. The event explorer, the live feed and a person's own page never hide them: that is where you look at your own test events, and each explorer row carries internal: true|false.

GET PROJECT/internal-identities/

The project's internal identities, newest first.

POST PROJECT/internal-identities/

{kind: "distinct_id", distinct_id, note?} or {kind: "property", property_key, property_value, note?}. At most 100 per project; a duplicate is a 400.

DELETE PROJECT/internal-identities/{id}/

Unmark one. Its events count again immediately.