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=30 for the last 30 days up to today. This is the default.
  • from=2026-11-01&to=2026-11-19 for whole UTC days, both included. to is 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"
  • start is what puts someone in a cohort and return is what counts as coming back. Each is an event’s exact name, or a page view as view:/path. Leave either out for any event or page view.
  • bucket is week, the default, or day. 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.