Reading Analytics

What a project's analytics kept is read in two places: Studio's Analytics screens, for the people of the organization, and the analytics module's read calls, with the project's secret key, for a server, a report or an agent. Both read the same rows, and neither reads past the project's retention (How long it is kept).

In Studio

Each screen reads the environment it is opened in, over the period chosen at its top: the last 24 hours, 7, 30 or 90 days.

A member of the organization reads every screen; changing an audience or the catalog's descriptions is an admin's (Organizations).

From a server

// server/weekly-report.ts
import { createServer } from "palbase/server";

const palbase = createServer({ url: process.env.PALBASE_URL!, secretKey: process.env.PALBASE_SECRET_KEY! });
const WEEK = 7 * 24 * 3600;

const summary = await palbase.analytics.getSummary({ query: { window_seconds: WEEK } });
console.log(`${summary.data.total} events by ${summary.data.unique_users} people`);
for (const e of summary.data.events.slice(0, 5)) console.log(e.name, e.count);

const countries = await palbase.analytics.getEventBreakdown({ query: { by: "country", event: "purchase", window_seconds: WEEK, limit: 5 } });
for (const row of countries.data.rows) console.log(row.value || "unknown", row.events, row.users);

const funnel = await palbase.analytics.runFunnel({
  body: { steps: ["signup_started", "signup_completed", "checkout_started"], window_seconds: WEEK, conversion_window_seconds: 24 * 3600 },
});
for (const step of funnel.data.steps) console.log(step.step, step.name, step.users, step.conversion_rate);

const retention = await palbase.analytics.runRetention({
  body: { first_event: "signup_completed", return_event: "app_opened", period: "week", periods: 8, window_seconds: 8 * WEEK },
});
for (const row of retention.data.rows) console.log(row.cohort_start, row.cohort_size, row.returns);

In a palbase/backend app the same calls are Palbase.analytics. A publishable key is refused every read (403): an app sends, and only the project's server reads.

Every read takes window_seconds, how far back to look: an hour unless said, 400 days at most, and never past the project's retention. The answers that page say next_cursor, which the next call passes as cursor; the last page has none.

Summary

GET /analytics/summary (getSummary): the window's events — total, by how many distinct ids (unique_users) — and its 50 most frequent names with their count. window_seconds in the answer is the window read, after the retention bounded it.

Events

Breakdown

GET /analytics/breakdown (getEventBreakdown) splits the window's events by one dimension, the most frequent value first: for each value, how many events had it and by how many distinct ids (users).

An absent or empty value is ""; a property that is not a string is its JSON (a number, true, an array). event narrows it to one event; limit is 10 unless said, 100 at most.

Funnels

POST /analytics/funnel (runFunnel) counts how many people took each step, in order, each within conversion_window_seconds of their first step.

Each step answers its place (step, from 1), its name, the users who reached it and its conversion_rate: its share of the first step's. A person's anonymous events count with their signed-in ones once an identify joined them.

Retention

POST /analytics/retention (runRetention) puts people in a cohort by the period in which they first did first_event, and counts how many of them did return_event in each period after.

The answer's rows are the cohorts, newest first: cohort_start, cohort_size, and returns, where returns[0] is the cohort's size and returns[k] the people back k periods later. observable says how many of the periods after have fully passed: a period still under way is not counted, so a young cohort's later columns are not zeros but not yet.

People, the catalog and audiences

GET /analytics/people, GET /analytics/people/{person_id} and GET /analytics/people/{person_id}/events find a person, read what is known of them and their timeline; GET /analytics/catalog lists the events a timeline can hold; the audience calls make and read audiences. See Web Analytics.

From the CLI

palbase analytics:summary --window 7d
palbase analytics:events --name purchase --window 24h --limit 20
palbase analytics:events --user 3f2c9a1e-…    # one person's, newest first

--window takes 30m, 24h, 7d; both commands read the environment chosen with palbase use or -E (CLI reference).

Errors

Related

• Analytics — what is kept, whose it is, and for how long
• Performance — timings, requests and debug history
• Web Analytics — sending, people and audiences
• Server SDK Overview — calls, refusals, retries and paging