{"uid":"cap_kjQjT4_sHXbQrv1MszQfB","slug":"netzhandwerker-cohort-retention-analysis-5747a7a7","name":"Netzhandwerker Cohort Retention Analysis","description":"Builds the cohort table from the events you pass: users grouped by the period of their first event, counted again in each following period. Returns the table per cohort, a retention curve across all cohorts, and, where events carry a value, cumulative value and value per user. The curve counts only cohorts old enough for a given period, so a young cohort is not scored as churn. Day, week and month are real calendar periods. Nothing is fetched, nothing is stored.","url":"https://tools.halowerk.com/v1/cohort/retention?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","properties":{"events":{"type":"array","maxItems":4000,"minItems":1,"description":"Each event needs user_id and a timestamp (time_unix_s in seconds since 1970, or time as ISO 8601). Optional: type and value. Any other field name is rejected rather than guessed. The service caps the whole request body at 256 KB, so long records reach that limit before maxItems."},"period":{"enum":["day","week","month"],"type":"string","default":"week"},"periods":{"type":"integer","default":12,"maximum":52,"minimum":1,"description":"How many periods the table runs, period 0 being the entry period."},"week_start":{"enum":["monday","sunday"],"type":"string","default":"monday"},"activation_type":{"type":"string","maxLength":120,"description":"If set, only events of this type put a user into a cohort. Without it the first event of any type counts."},"retention_types":{"type":"array","items":{"type":"string"},"maxItems":50,"description":"If set, only events of these types count as being active. Without it every event counts."},"timezone_offset_s":{"type":"integer","default":0,"maximum":50400,"minimum":-50400,"description":"Offset from UTC in seconds used to place period boundaries."}}},"responseSchema":null,"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.002","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.002/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.002","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.002","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_Dod_k3oM8hJN_JnS6toZg","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.002","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Builds a cohort retention table from raw events, grouping users by their first-event period and tracking re-engagement across subsequent periods, with optional value accumulation metrics.","exampleAgentPrompt":"Build a weekly cohort retention table from these events for the past 12 weeks — users should only enter a cohort when they trigger a 'signup' event, and count as retained only when they trigger a 'purchase' event. Week starts on Monday.","exampleUseCases":[{"title":"SaaS monthly user retention dashboard","prompt":"I have 3,000 user events from our app over the last 6 months. Can you group users into monthly cohorts based on when they first signed up and show me how many returned in each of the following 6 months? Period should be month, and only 'login' events should count as retention."},{"title":"Mobile game weekly re-engagement analysis","prompt":"Analyze these player events to show me weekly cohort retention for the past 12 weeks — players enter a cohort on their first 'level_start' event and are counted as retained in later weeks if they trigger any 'level_start' or 'level_complete' event. Start weeks on Sunday."},{"title":"E-commerce cohort revenue tracking","prompt":"Here are purchase events with values for 2,000 customers over the last 8 weeks. Group customers into weekly cohorts by their first purchase and show me cumulative revenue and revenue per user for each cohort across all 8 periods."}],"resultDescription":"Returns a per-cohort retention table showing user counts in each subsequent period, a blended retention curve across all cohorts (excluding cohorts too young to score a given period), and — when events carry a value field — cumulative value and value-per-user metrics per cohort per period.","failureModes":["Events missing user_id or timestamp fields return a validation error","Unknown field names in event objects are rejected rather than silently ignored","Request body exceeding 256 KB is rejected regardless of item count","Invalid timezone_offset_s outside [-50400, 50400] range returns an error","Periods value exceeding 52 causes a validation error","activation_type or retention_types referencing event types not present in the data return empty cohorts without error"],"whenToPreferThis":"Choose this endpoint when you have raw event logs and want server-side cohort grouping and retention curve computation without storing data or implementing period-boundary logic yourself. It is especially useful when you need real calendar periods (day/week/month) with correct timezone alignment, want to separate activation events from retention events, or need cumulative value metrics alongside user counts. Prefer it over spreadsheet or client-side solutions when event volume is up to 4,000 records and you want a stateless, pay-per-call computation.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-12T06:41:41.011Z","isFirstParty":false,"canonicalSlug":"netzhandwerker-cohort-retention-analysis-5747a7a7"}