Querying events

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:

Authorization: Bearer tk_your_token

Two scopes: read covers everything read-only on this page, and read_write adds creating annotations — and nothing else. No scope 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}.

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.

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.

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

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.

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.

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