Inspect events and customer cohorts

Use event discovery to verify instrumentation and connect behavior to customer investigations. The Events and Cohorts views provide behavioral context alongside the agent and CLI workflows. For property names, types and presence counts, see event property schemas.

For typed measurements, frozen evidence and exact contributor pages through MCP or CLI, see measure product events. That guide also covers confirmed creation and replacement of derived audiences from complete result selections through MCP and CLI, and exact-generation reuse in product queries.

Inspect an event

Open Analytics → Events & trends, choose an event name, and review its recent volume and identified customers. If an event is missing, confirm the SDK sent it after identity was established and that the current project and time window are correct.

Open a customer from the triggerer list to compare the event with their errors, traces, replay, releases, and AI calls. Anectico labels each triggerer with the recognizable identifier used for the event while keeping the canonical person behind the link; internal person UUIDs are not customer display names. Event volume alone does not explain an outcome.

Discover the event catalog with an agent or CLI

Use the MCP read action get_event_catalog through execute_read_action, or run:

anectico --project PROJECT_UUID analytics catalog \
  --start-time 2026-09-10T00:00:00Z \
  --end-time 2026-09-11T00:00:00Z \
  --environment production --prefix checkout --limit 50

MCP arguments use project_id, start_time, end_time, environment, prefix, limit and cursor. The equivalent REST endpoint is GET /api/v1/events/catalog. The read requires analytics:read; MCP also requires mcp:read. A project-scoped credential supplies its project automatically and cannot read another project. Organization credentials must select a project. The project must be active, and the entire window must remain within its currently readable history.

The start is inclusive and the end exclusive. Supply RFC3339 times with millisecond precision or coarser and a window of at most 90 days. A future end time is allowed, but does not establish completeness for the future portion of the window. Environment matches exactly; omitting it includes all environments. Prefix matches event names literally and case-sensitively: % and _ are ordinary characters. Event names are returned in ascending order, with 50 names per page by default and a maximum of 200.

Each entry contains name, count, first_seen and last_seen. Counts represent converged event occurrences in the selected window, including delivery retries that collapse into one event. They are not unique people or lifetime totals; first/last times also refer only to the selected window. No property examples or person identifiers are returned.

When has_more is true, pass next_cursor as cursor (CLI --cursor) with the same project, window, environment, prefix and page size. Cursors expire 15 minutes after the first page; later pages do not extend that lifetime. Start a fresh read after expiry. Invalid or changed filters are rejected. Resource-limit failures return an error for the whole page; narrow the window or prefix before retrying.

ingested_before records the initial receipt cutoff. observed_from and observed_until describe the database-read interval. These do not establish a consumption watermark or freeze the source: delayed consumption and deletion can change subsequent pages. platform_completeness and upstream_completeness remain unknown, including when the catalog is empty. An empty page cannot prove that no customer action occurred. Catalog counts are live evidence, not a saved analytics result. The dashboard's existing Events view is a separate investigation workflow.

Create a cohort

Open Customers → Cohorts and create a reusable customer group. Anectico supports behavioral, property-based, and static definitions. Use a stable name that describes membership rather than the campaign that first needed it.

Choose Refresh after changing upstream data or when current membership is required immediately. Open the cohort's members to validate representative customers before using it in a feature rollout or watched alert.

For a behavioral or property cohort, choose Preview current matches before saving. Preview is a point-in-time, non-mutating evaluation: Anectico shows the complete matching count, a bounded sample of people, the evaluation time, and the definition hash. The evaluation time is the shared UTC anchor selected when evaluation starts and the exclusive end of behavioral windows. Saving or editing a definition does not make an older preview current; run preview again after every definition change.

Preview checks current project history, tracking declarations, source permissions and content policy before evaluation and again before returning the count or sample. Profile predicates need persons:profile:read; sensitive event filters, including declared-sensitive properties and nested content inside selected values, need agents:content:read and an allowing content policy. The check includes candidate events that do not match the filter. Profile checks cover the age of all consulted profiles, even when none match. Missing source evidence, expired history or a policy or declaration change causes the whole preview to fail; it does not return a partial audience.

All behavioral conditions are read together from one source snapshot, preserving each condition's own event, filters and time window. The complete preview is limited to 250,000 candidate events and 64 MiB of inspected source and condition-count input. Nonmatching events count toward these limits. A definition can include up to 64 behavioral conditions; the encoded behavioral request and generated query are each limited to 256 KiB. Narrow the window or event selection if a limit is exceeded. These are evaluation guardrails, not measured capacity or incoming-event completeness. All behavioral conditions share one owning identity snapshot for up to 250,000 distinct event identifiers across the definition. Event identifiers mapped to the same person have their matching counts combined before count thresholds are applied. Nonmatching candidate events also need a valid identity mapping. Missing or invalid mappings refuse the entire evaluation; retry after identity processing recovers. An event identifier equal to a person UUID is accepted only when Persons explicitly resolves that identifier to a live canonical person.

Property pages carry an owning revision for the selected field's source, including nonmatches and property removals. A change between pages or during the final checks refuses evaluation, even if a property is changed back to its original value. Changes to unrelated fields do not change that revision. Each property condition is limited to 500,000 source profiles and 32 MiB of encoded source input, counted across all its pages; removed-property winner records also count. Repeated conditions each perform their own bounded read. The whole definition has a separate 64 MiB budget for retained evaluation input, including condition counts and matching identities. Narrow the definition if a limit is exceeded.

The dynamic-cohort population ceiling is 500,000 matching people. Preview also has a 30-second execution deadline; large property sources can time out below the population ceiling. A timeout returns no partial audience. These limits are not a promise that every permitted size finishes. If a combined definition exceeds the population limit, preview, definition evaluation and refresh fail; refresh keeps the previously stored generation. Narrow the definition before retrying. Behavioral windows must be between 1 and 365 days. Each behavioral condition uses its configured number of 24-hour days, ending at one shared UTC instant for that evaluation. Events exactly at the end instant are excluded. Refresh and definition edits retain this evaluation boundary with the resulting generation. This shared time boundary does not freeze incoming events or changes to person properties. Refresh and definition edits repeat the complete behavioral count observation and owning identity and property checks before writing the new generation. Changes to any condition's observed aliases, source counts or matching counts refuse the operation, even when qualifying membership would be unchanged. An unavailable reader, changed mapping or property source, invalid profile identity, or observed organization/project deletion refuses the operation. Count thresholds, result limits and combined conditions cannot hide missing identity evidence. Failed checks before commit preserve the previous stored membership and generation. If mirror preparation has already started, the alert mirror can remain unavailable until a successful refresh restores it; a failed or canceled refresh never activates a partial audience.

These checks do not freeze incoming events or make reads across services an atomic transaction. A late event can affect a later refresh, and source changes after the final check can occur before the new generation becomes visible. A cohort is a recorded evaluation, not a continuously current membership guarantee.

Static cohorts use explicit full-list replacement. Choose Replace members, supply the complete desired list of person UUIDs or project-scoped distinct IDs, and review the warning before submitting. The operation never appends. An empty submission intentionally clears the cohort. Anectico fences the write with the generation that was current when the dialog opened, so a concurrent refresh or edit is rejected instead of overwriting newer membership.

After a static create or replacement, keep the resolution summary with the change record. It reports:

• input values received;
• inputs that resolved to a known person;
• unique canonical people written;
• duplicate inputs that collapsed to an already-resolved person; and
• unresolved inputs, including the exact unknown values to correct.

Unknown values are skipped; they are never treated as new people. The summary remains visible in the cohort workflow so a successful request with unresolved inputs cannot be mistaken for a lossless import.

Audit membership generations

Choose History on a cohort to inspect immutable materialization generations. The current and retained states are explicit, along with total members, added and removed counts, refresh reason, actor, materialization time, definition snapshot and hash, and Alert-targeting delivery status. Choose Open generation to inspect the exact member list for a retained historical generation. Generations marked Not retained keep their audit metadata but no longer expose a member list.

History counts require access to the sources of both the selected and preceding generation, because added and removed counts compare those member sets. Reading a retained member list requires access to that generation's own sources. A later sensitive-property declaration can restrict reads of existing generations; editing a definition or retiring its tracking plan does not remove protection from those historical sources.

Update and refresh responses apply the current source permissions and content-erasure evidence to their counts too. membership_withheld: true means the scalar member count is withheld; its zero is not an empty cohort. Generation history also returns deltas_withheld: true when added and removed counts cannot be disclosed, even if the current member count is available. MCP and CLI cohort reads display unavailable for these values. The dashboard shows Membership unavailable, keeps configuration and history accessible, and only offers member inspection when the generation can be read. Authorized refresh and edit actions remain available.

Ordinary dynamic generations retain the content-erasure revisions observed before evaluation. A subject-content clear invalidates older generations that depend on that content class in the same project, even when the subject was not a member. Content-dependent members and counts remain unavailable if their original evidence is missing, pending or changed; restoring source rows does not restore an old generation's evidence. Refresh creates a new generation from current sources. Static supplied membership and content-independent generations do not inherit that dependency. A fresh generation's deltas remain unavailable if the preceding generation cannot be read. An authorized get_cohort_members response for the exact returned generation can establish its count, including zero. An error after an update or refresh does not prove the change was rolled back: the result's source may have become unavailable after the write. Inspect the cohort and its history before retrying.

The Alert-targeting badge describes whether the current generation has reached the audience mirror used by alert evaluation:

• Syncing — delivery is pending, including a retry in progress or queued;
• Failed — the generation is not available to Alert targeting; and
• Synced — Alert targeting is evaluating this generation.

When membership is withheld, the dashboard shows Alert targeting unknown even if an earlier delivery succeeded. Delivery status alone does not establish current source validity. Do not assume an updated cohort is active for Alerts until the badge reads Synced. Retry a failed refresh or contact an administrator if delivery does not converge. A generation retired because its source evidence failed during delivery cannot be reactivated by a delivery retry; Refresh creates a newer generation from current sources.

Cohort definitions require cohort read access. Computed members, counts and targeting decisions also require the scopes of their sources. Event-property filters outside Anectico's exact operational-metadata allowlist require agents:content:read as well as analytics:read; profile predicates require persons:profile:read. Combining predicates combines these requirements. A count can reveal a restricted property even without returning its raw value. Creating, editing, refreshing, and replacing membership need cohorts:write, which every member role holds. Deleting a cohort is destructive and needs cohorts:delete, a dedicated organization owner or admin permission. The UI remains inspectable but removes mutation controls when the required permission is missing.

Deleting a cohort is destructive. Feature flags that target it stop matching those members, so remove or replace those dependencies first.

Keep definitions trustworthy

• Prefer stable identity and normalized properties.

• Avoid static lists when a behavioral or property definition expresses the rule.

• Sample members after creation and after significant instrumentation changes.

• Record why a cohort exists in its name or team runbook.

• Send diagnostic events

• Identify customers

• Check rollout health

Live event-triggerer reads preserve the exact event name, including leading or trailing whitespace. Their optional property-key filter retains its restricted key syntax; use native typed analytics filters and frozen participant pages for arbitrary property keys. Empty triggerer results contain an empty array.