Reading data
Get events, counts, funnels and people back out with a read key.
These take a read or private key as Authorization: Bearer. Everything returns JSON.
curl "https://api.snekot.co/v1/events?channel=payments&limit=10" -H "Authorization: Bearer YOUR_READ_KEY"
| Endpoint | Query | Returns |
|---|---|---|
GET /v1/project |
The project’s name, plan, and events used this month. | |
GET /v1/channels |
Every channel, with its event count and latest event. | |
GET /v1/events |
channel, event, user, q, since, until, limit, cursor |
Events, newest first. |
GET /v1/insights |
Every insight and when it was last set. | |
GET /v1/charts |
event, and a range |
An event’s count per day, the total, and the total for the period before. |
GET /v1/funnel |
step repeated, and a range |
How many people reached each step. |
GET /v1/retention |
start, return, bucket, and a range |
Cohorts by when people first came, and how many of each came back in each week after. |
GET /v1/top |
by, event, limit, and a range |
The most frequent values. |
GET /v1/sources |
path, source, kind, campaign, country, region, city, host, browser, os, device, and a range |
Page views and visitors, and where they came from: sources, countries, campaigns, pages and the rest of what the Views page shows. |
GET /v1/experiments |
name, goal, and a range |
Each A/B test: visitors, conversions and rate per variant, and whether the difference is likely real. |
GET /v1/export/events.csv |
channel, event, user, q, since, until |
Every matching event, as CSV. |
GET /v1/export/views.csv |
by, and a range |
Page views counted every way the Views page counts them, as CSV. |
GET /v1/subscribers |
q, limit, cursor |
Newsletter subscribers, newest first. |
GET /v1/export/subscribers.csv |
q |
The newsletter list, as CSV. |
GET /v1/users |
q, limit |
People, most recently active first. |
GET /v1/users/:id |
One person, with their latest 50 events. |
Events
q is free text, matched against names, descriptions, user ids and tags. since and until are ISO 8601 times. limit is 25 by default and 100 at most.
When there are more, the answer has a next value. Send it back as cursor for the page after:
{ "events": [ … ], "next": "2026-11-19T17:55:38.440Z|9" }
Ranges
Charts, funnels and top values take a range in one of two ways:
days=30for the last 30 days up to today. This is the default.from=2026-11-01&to=2026-11-19for whole UTC days, both included.tois today if left out.
A range covers at most 366 days. Counts are per day, or per week once the range is longer than 92 days.
Funnels
Repeat step two to six times, in order:
curl "https://api.snekot.co/v1/funnel?step=Account%20created&step=Added%20to%20cart&step=Order%20placed&days=30" \
-H "Authorization: Bearer YOUR_READ_KEY"
People are counted by user_id, and each step must come after the one before it. The answer has the people at each step, the conversion from first to last, and the same figure for the period before.
Retention
People are grouped into cohorts by the week they first did something, and each cohort is followed week by week:
curl "https://api.snekot.co/v1/retention?start=Account%20created&return=Order%20placed&days=56" \
-H "Authorization: Bearer YOUR_READ_KEY"
startis what puts someone in a cohort andreturnis what counts as coming back. Each is an event’s exact name, or a page view asview:/path. Leave either out for any event or page view.bucketisweek, the default, orday. Weekly cohorts cover the past 56 days unless a range says otherwise and at most 26 weeks; daily ones cover 14 days and at most 31.- Cohorts end on the range’s last day, so the newest one is still running. A range that is not whole weeks is stretched back to one.
{
"bucket": "week",
"people": 412,
"cohorts": [
{ "start": "2026-09-28", "people": 58, "returned": [58, 21, 17, 15, 14, 12, 12, 11] },
{ "start": "2026-10-05", "people": 61, "returned": [61, 25, 19, 16, 15, 13, 12] }
],
"overall": [1, 0.38, 0.29, 0.26, 0.24, 0.21, 0.2, 0.19]
}
returned[0] is the cohort’s own week, counted from the moment each person joined it; returned[1] is the week after, and so on up to the week now running. overall is the share that came back in each period, across the cohorts old enough to have reached it.
People are counted by user_id, or by visitor when no one was named. A visitor is only the same person from one day to the next when the site remembers them, so retention says most about signed-in people and remembered visitors. Someone counts as new if they did nothing in the year before.
Top values
by is event, channel, user, or a tag as tag:<key>, such as tag:plan. Events without the thing being ranked are left out.
CSV exports
Three endpoints answer with a CSV file instead of JSON. All are streamed, so a long range does not have to fit in memory on either side:
curl "https://api.snekot.co/v1/export/events.csv?channel=payments&since=2026-01-01T00:00:00Z" \
-H "Authorization: Bearer YOUR_READ_KEY" -o payments.csv
Events takes the same filters as GET /v1/events, without limit or cursor: the file holds every match, newest first. Its columns are id, created_at, channel, event, description, icon, user_id, notify and tags, where tags is the event’s tags as JSON.
Views takes a range, and holds one row per value: breakdown, value, views, visitors, from, to. Without by it has every breakdown; with it, one of page, entry_page, hostname, referrer, channel, campaign, country, region, city, browser, os, device, language, outbound or download.
Subscribers holds the newsletter list, newest first, or the part of it q matches: email, name, subscribed_at, unsubscribed_at, source and properties, where properties is JSON.
Text that a spreadsheet would run as a formula, which is anything starting with =, +, - or @, is written with an apostrophe in front. An event’s text comes from whoever posted it, and a file should be safe to open.
In the app, the download button on Events exports what the feed is showing, the one on Views exports that page’s breakdowns for the period chosen, and the one on People, Subscribers exports the list or what its search matches.
A public dashboard
Under Setup, Public dashboard, the owner can turn on a link that shows the project’s overview to anyone who has it, with no sign-in: the headline figures and a chart, the top pages, sources and countries.
The link ends in a long random token. It opens that one page and nothing else: events, people and the insights your product sets are not on it, and it cannot change anything. Turn it off, or make a new link, and the old one stops working at once.
Next Assistants (MCP)