/cohorts-and-events

name: "PostHog Cohorts & Events"
description: >
  PostHog cohorts (saved user/group segments), raw analytics events, and
  timeline annotations. Read-only lookups — listing and retrieving existing
  records, not defining new segments or emitting events.
when_to_use: >-
  When looking up a saved user segment, raw event activity, or a timeline
  annotation in PostHog. Use when: posthog cohort, posthog event, posthog
  annotation, user segment, event query, cohort membership, or deploy
  marker.

PostHog Cohorts & Events

Overview

A cohort is a saved segment of users or groups — static (a fixed list) or dynamic (defined by a rule that PostHog re-evaluates). Events are the raw analytics stream: every tracked interaction, tied to a person or `distinct_id`, carrying whatever properties the client's application sent. Annotations are timestamped notes on a project's timeline — deploys, incidents, config changes — used to explain a shift in a metric. This skill covers looking these up, not defining them.

Anti-triggers

• **Aggregated trend or funnel analysis** — don't hand-aggregate raw events

into a trend; use `insights-and-dashboards`, which is what PostHog's own computed insights are for.

• **Feature-flag targeting rules** — a cohort can target a flag, but this

skill only covers listing and retrieving cohorts and events themselves; use `feature-flags-and-experiments` for what a flag or experiment is configured to target.

• **Auth, scopes, or rate-limit behavior** — use `api-patterns`.

Core Concepts

Cohorts group people or groups by shared property or behavior. Events carry an event name, a `distinct_id`, a timestamp, and a properties payload whose shape depends entirely on what the client's application instruments — PostHog imposes no fixed schema on event properties. Annotations are lightweight, timestamped, and scoped to a project (or a specific insight), and exist specifically so a human reviewing a metric later can see "what changed here."

API Patterns

The confirmed read tool family for this domain:

• Cohorts: list, retrieve
• Events / Annotations: list, retrieve

This plugin exposes only these read tools; there is no cohort-definition, event-ingestion, or annotation-authoring tool in this plugin's surface. PostHog's own docs carry the exhaustive tool catalog: [posthog.com/docs/model-context-protocol/tools](https://posthog.com/docs/model-context-protocol/tools).

Common Workflows

SOC analyst checking recent error events for a client's app

1. List events scoped to the relevant event name (e.g. an error or exception event the client's app emits) and a bounded, recent date range 2. Retrieve individual events for detail if a pattern needs closer inspection 3. Cross-reference against `insights-and-dashboards` if the client already has an error-tracking dashboard — don't re-derive a trend PostHog has already computed

vCIO correlating a reported slowdown with a recent deploy

1. List annotations on the relevant project or insight for the reported time window 2. Match a deploy or config-change annotation against the metric shift the client is asking about 3. Report the correlation, not a causal claim — this skill surfaces timeline markers, it doesn't establish root cause

Confirming a specific user's cohort membership before escalating a bug

1. Retrieve the cohort in question 2. Check whether the reported user/`distinct_id` matches the cohort's current membership 3. Note that dynamic cohorts re-evaluate — membership can have changed since the client last checked

Gotchas

• **Event properties may carry PII.** Whether an event contains emails,

user IDs, or other identifying data depends entirely on what the client's application sends — this plugin has no way to know in advance. Treat event and cohort output as potentially sensitive by default; see [GOVERNANCE.md](../../GOVERNANCE.md), *Data handling*.

• **Bound event queries by date.** Event volume in an active project can be

large; an unbounded pull is a way to exhaust rate limits and return more data than the question needs.

• **Dynamic cohort membership is a moving target.** A cohort defined by a

rule re-evaluates over time — "who's in this cohort" answered now may not match what it was when an incident happened.

Related Skills

• [Insights & Dashboards](../insights-and-dashboards/SKILL.md) — Computed trends and funnels
• [Feature Flags & Experiments](../feature-flags-and-experiments/SKILL.md) — What a cohort targets
• [API Patterns](../api-patterns/SKILL.md) — Auth, scopes, and error handling