analytics_retention_run

Tool

analytics_retention_run

Measure day-N retention over the analytics semantic layer for the current product: of the subjects whose FIRST matching cohort event falls in a bucket, how many produced a return event on day N (within `return_window_days` after it). The cohort key is `subject` — an event property (`props.<key>`, e.g. the customer product id) or `identity` for the entity's declared identity columns — and each subject is counted exactly once. Deterministic: entity and dimension names are resolved against the semantic catalog, never generated. A bucket whose day-N horizon has not elapsed yet is still returned, with `retained` and `rate` NULL rather than 0 — null means "not measurable yet", 0 means "measured, nobody came back", and a caller must not confuse them. `total` therefore covers the measurable buckets ONLY, so a half-elapsed cohort never drags the headline rate down; `meta.unmeasurable_buckets` says how many were left out.

Behavior

HTTP: POST /analytics/retention/run

Arguments

Name	Type	Required	Description
to	string	•	Inclusive last day of the cohort range (UTC)
day	integer	•	N: a subject is retained if it has a return event at least N days after its cohort event
from	string	•	Inclusive first day of the cohort range (UTC)
grain	string	•	Cohort bucket size, applied to each subject's FIRST cohort event
cohort	object	—	The starting event; empty filters mean any row of the entity
entity	string	•	Semantic view name from the catalog
return	object	—	The coming-back event; empty filters mean any row of the entity
subject	string	•	Cohort key: "identity" or `props.<key>`
return_window_days	integer	—	Length of the window that opens on day N; a return event must fall inside it

Response

Field	Type	Always
meta	object	•
total	object	•
buckets	array	•

Try it

Measure day-N retention over the analytics semantic layer for the current product: of the subjects whose FIRST matching cohort event falls in a bucket, how many produced a return event on day N (within `return_window_days` after it).

When to use

Example

Ask your agent something like this:

Measure day-N retention over the analytics semantic layer for the current product: of the subjects whose FIRST matching cohort event falls in a bucket, how many produced a return event on day N (within `return_window_days` after it).

The agent will invoke analytics_retention_run with these arguments:

{
  "to": "<to>",
  "day": "<day>",
  "from": "<from>",
  "grain": "<grain>",
  "entity": "<entity>",
  "subject": "<subject>"
}