Investigate accounts and segments

Accounts are built from SDK group() calls. They let a B2B team see customer activity, errors, and impact at a company, workspace, tenant, or other group boundary. Your agent reads accounts and manages account segments through MCP or the CLI. The Console has no Accounts page and no Account Segments page.

Account watches retain directly declared account members, including unidentified traffic. An unmapped member cannot pull another person's identifiers into the account. A member-identifier count is not a unique-people count; canonical people need an identifier Anectico resolved. Attribution is as reliable as your application’s customer identification; telemetry does not authenticate each end user. Member lists retain unresolved identifiers. A person link appears only when Anectico resolved that exact identifier; declaring someone's person ID does not create a person link. The member total still includes every returned identifier.

Create account identity in the SDK

After identifying a customer, call group with a stable group type and key:

JavaScript / TypeScript

anectico.group('company', 'acme', { name: 'Acme Inc', plan: 'enterprise' });

Python

client.group('company', 'acme', {'name': 'Acme Inc', 'plan': 'enterprise'})

Go

if err := client.Group(ctx, "company", "acme", map[string]any{
	"name": "Acme Inc",
	"plan": "enterprise",
}); err != nil {
	return err
}

Swift (iOS)

Anectico.group(type: "company", key: "acme", set: ["name": "Acme Inc", "plan": "enterprise"])

Kotlin (Android)

Anectico.group("company", "acme", mapOf("name" to "Acme Inc", "plan" to "enterprise"))

React Native

await Anectico.group('company', 'acme', { name: 'Acme Inc', plan: 'enterprise' });

Flutter

await Anectico.group('company', 'acme', set: {
  'name': 'Acme Inc',
  'plan': 'enterprise',
});

Use one meaning per group type. Do not alternate between company, account, and workspace for the same domain object. Group properties should be small, current facts—not secrets or event history.

Approve configuration changes

Every management write through MCP, REST or the CLI first returns a server preview and changes nothing. It includes complete before and proposed definitions, required permissions and a confirmation token. Customer-authored configuration is marked as untrusted data. Creation IDs and commit timestamps are assigned at apply; the preview states which values are generated then.

Approve that state, then repeat identical arguments with MCP confirm_token, CLI --confirm-token TOKEN, or REST header X-Anectico-Confirm-Token: TOKEN. Keep the same body, version arguments and retry key. A changed state, source or argument requires a fresh preview and approval. Local --yes is no longer accepted.

Creation needs a stable idempotency_key (1–128 bytes), supplied with CLI --idempotency-key KEY or REST Idempotency-Key: KEY. Identical retries return the first committed result, even after the object changes or is deleted; they create nothing new. Changed arguments cannot reuse the key. Current permissions and privacy restrictions still apply when reading a receipt.

Create uses a retry key. Updates and deletion require exact expected_updated_at (--expected-updated-at TIMESTAMP). Updating replaces supplied filters and keeps omitted fields. Its preview shows every current and proposed filter value. list_account_segments and anectico segments list take limit and cursor and return the next cursor. Use segment_id / --segment-id SEGMENT_UUID for one full definition. The matching-account preview is a separate read; it does not save rules.

Ask your agent

"Find the account with key acme of type company and show me its members and its activity for the last 7 days."

"Create a segment of company accounts whose plan is enterprise. Preview the accounts it matches before you save it."

Job	MCP tool or action	CLI command
Find accounts by key or name; with no arguments, list the account types in use	search_accounts	anectico accounts list, anectico accounts types
Read one exact account profile; optionally read retained event activity	get_account_profile through execute_read_action	anectico accounts get <group-type> <group-key> --include-stats
Read one account's merged activity timeline	get_account_timeline	anectico accounts timeline
List the people who belong to an account	list_account_members	anectico accounts members list
Move a person to another account of the same type	move_account_member	anectico accounts members move
Remove a person from an account	remove_account_member	anectico accounts members remove
Delete an account definition	delete_account	anectico accounts delete
List the account segments of a project	list_account_segments	anectico segments list
Preview the accounts one segment matches	preview_account_segment	anectico segments preview
Create, change or delete a segment	create_account_segment, update_account_segment, delete_account_segment	anectico segments create, update, delete

Reading accounts needs groups:read. Changing members needs groups:write, and deleting an account needs groups:delete. Segments need account_segments:read, account_segments:write or account_segments:delete. Over MCP every call also needs mcp:read or mcp:write. To erase an account, see Erase an account.

What your agent gets back

An account search returns the account type and key that the other account reads need. A timeline returns the merged activity of every person in the account, newest first. A member list returns people with their person IDs, and can include removed members as history. A segment read returns its name, account type and filters. A segment preview returns a count and a list of up to 200 current matching accounts. Writes preview first and need a confirmation.

Read one exact account profile

Use the exact project, account type and key. Case, surrounding spaces and Unicode matter; a search's single substring match does not establish an exact profile. Unsupported control or invisible characters are refused before lookup. For example:

{
  "action": "get_account_profile",
  "arguments": {
    "project_id": "PROJECT_UUID",
    "group_type": "company",
    "group_key": "acme",
    "include_stats": true
  }
}

Send this through execute_read_action, or run anectico accounts get company acme --project PROJECT_UUID --include-stats -o json. The profile read needs groups:read, plus mcp:read over MCP. It needs no confirmation. A project-bound credential may omit the project or name its own; another project is refused without revealing whether it exists.

The result includes exact selectors, profile_revision as a decimal string, profile creation and update times when known, and properties. Read properties_availability, properties_policy_outcome and properties_reason together. An allowed empty bag is available with reason empty; withheld with policy_denied differs from unavailable with policy_unavailable. not_stored means the values were never kept. A retained bag can also carry older not-stored provenance (partially_not_stored). Withholding markers remain visible; do not interpret them as an empty measured bag. MCP marks the property document and its keys and values as untrusted data. Exact selector values remain available separately from their display labels.

Returned properties are limited to 64 KiB of UTF-8 JSON. Whole entries are selected in ascending key order, preserving policy markers first, and stop before the next entry would exceed the limit. properties_truncated, properties_returned_bytes and properties_selection disclose this cut. A cut bag is incomplete; the bound changes only the returned projection.

Statistics default to not_requested; omit --include-stats when you only need the profile. When requested and successful, stats_availability is available and stats.event_count is a decimal string. It counts retained product-event activity for this exact account, not members, people, revenue or expected service health. Missing first_seen and last_seen stay null. A successful "0" measures that retained source only. read_coverage names product history and its retention floor when known. This read accepts no occurrence interval, so coverage is unknown with no_requested_interval; upstream completeness stays unknown.

If statistics are unconfigured, refused, canceled or fail, the authorized profile is still returned with stats_availability: "unavailable", a typed stats_reason and no stats and count. A query-budget refusal also carries stats_budget_refusal. Unknown is never zero. A failed or erased profile remains a failed read. Every call checks the current account; there is no account proof page or promised archive of expired activity.

Open the proof

Accounts, members and segments have no proof page, and no account tool returns a link. For a link that shows one customer, ask your agent to read a member with get_person_timeline, get_person_profile or resolve_person. Each returns a link to the read-only person page. See proof pages. For account-level numbers that a person can open, ask for an account-unit measurement (below); its result has a link in the result viewer.

Investigate an account

Start with the account symptom, then read an affected customer or issue for the detailed causal path. Read the account's activity first. A timeline is read in pages; keep the same dates while you page, and begin again if you change them.

Read the account's members for the people behind it. Membership entries represent aliases, so two entries can belong to one person; the entry total is not a unique people count. A profile's updated time does not establish when the account last had activity.

To delete an account definition, ask your agent to use delete_account. It is refused while the account has active members, so move or remove them first. Historical telemetry keeps its attribution.

If an account is empty, verify group() runs after identify() and before the relevant events. A group assertion records membership even when no optional properties are supplied. Events sent from a server with the Go or Python SDK must name their account on the event or the request; see Servers: name the account on each event.

Create an account segment

An account segment is a reusable filter for important accounts. Segments can be used by watched-account alerting, so validate the current membership before relying on escalation.

A segment has a name, one account type (a known group type or your own custom type) and a list of filters, each {field, op, value}. All filters must match. Text conditions include "is", "contains" and "starts with"; numeric comparisons use a number value. A segment with no filters matches every account of that type. Ask your agent to preview a saved segment: the preview returns a count and a list of up to 200 current matching accounts, so you can check several matching and non-matching accounts after an edit.

Before deleting a segment, update any alert routing that uses it. Anectico refuses to delete a segment while an active alert rule still references it, and the refusal explains that dependency; disable or retarget the rule, then retry. To change who an alert notifies, open Connections and notifications (/connections) in the Console; see the Console guide.

Segment by account properties

A trend, funnel or retention measurement can break its results down by a current account property instead of an event property: set breakdown.source to account and breakdown.account_type to the group type (company, workspace, …). The value is the account's property as it stands today, looked up through the event-time account key each contributing event carried — never a claim about what the property held when the event happened, and never the plan or region of some other member of the account. Requires groups:read.

An event that carried no key for that account type — the customer was never grouped, or the group call had not run yet — falls in the measurement's missing group. See Break down results for the full contract: the display limit, tie-breaking, the subject bound, and how this differs from breaking down by a current person property (persons:profile:read) or by the event's own property.

Measure an account funnel

A funnel can count accounts instead of people: set unit to {"kind": "account", "account_type": "company"} (or your own group type). Each step reads that occurrence's own event-time account key, so one company converts once however many of its employees acted along the way — an early-stage step by one employee and a later step by another still complete the same account's funnel. One person's two accounts stay two separate entrants: acting for both Acme and Globex enters the funnel twice, once per account, never merged into one identity.

An occurrence with no key for the chosen account type — the actor was never grouped under it, or the group() call had not run yet — is observed quality, not an entrant: it is counted in that window's account_attribution.missing_events and never enters the funnel. account_attribution also reports attributed_events, so you can see how much of the window's activity actually carried the key.

An account-unit funnel accepts event filters, filter_group, and explicit accounts filters (restricting entry to named account keys); it refuses top-level person-property filters and audience cohorts, because whether one employee or every employee should qualify a company for a step is not decided for you. It can optionally break down by a current account property the same way trends do (above) — never by a person property, since one account has many people and which one's profile would label it is not decided for you either.

Inspecting one account's frozen chain (analytics result contribution, or get_analytics_contribution in MCP) lists that account's member drill-down: each chain event's distinct_id is the actor of that specific occurrence, so one account's chain can name several different employees across its steps. The account is what progressed through the funnel; no single employee is claimed to have converted individually.

Reading an account-unit funnel result — the result itself, its participants, contributions, and any export — needs groups:read in addition to analytics:read, checked on every read so a revoked scope stops disclosing it at once. An account-unit selection can never be saved as a reusable audience (AUDIENCE_ACCOUNT_UNIT_UNSUPPORTED); read its account contributors directly instead.

Measure account retention

Retention can count accounts instead of people the same way: set unit to {"kind": "account", "account_type": "company"} (or your own group type). An account's cohort is its first qualifying entry by any member inside the entry window — Acme's cohort date is whichever employee signed up first, not a per-employee date. An account returns in a period when any member's qualifying event carries its key, so different employees can anchor the entry and produce the return. Every calendar period (day, week, month) and both return criteria (exact period, on or after) work the same as person retention.

A member who later moves to another account never returns the old one: attribution comes from the event's own key at the time it happened, never from where that person works today, so a later membership change cannot rewrite an earlier account's history. An occurrence with no key for the chosen account type is observed quality, not an entry or a return: it is counted in that window's account_attribution.missing_events, and account_attribution.attributed_events reports how much of the window's activity actually carried the key.

An account-unit retention accepts event filters, filter_group, and explicit accounts filters; it refuses top-level person-property filters and audience cohorts, for the same reason an account funnel does. It can optionally break down by a current account property, never by a person property.

Inspecting one account's frozen return evidence (analytics result contribution, or get_analytics_contribution in MCP) names the actor of the cohort anchor and of each disclosed return — one account's evidence can name several different employees across its periods. The account is what returned; no single employee is claimed to have been individually retained.

Reading an account-unit retention result — the result itself, its participants, contributions, and any export — needs groups:read in addition to analytics:read. An account-unit selection can never be saved as a reusable audience, and a metric watch refuses an account-unit retention (or funnel) the same way it refuses one with no eligible person population.

• Identify customers
• Create alerts
• Measure product analytics

For lossless timeline continuation, echo the returned opaque cursor and keep the same account, project, dates and signal filter. Pages remain bounded when many occurrences share a timestamp. Retain each row's item_id and project_id; a shared timestamp, summary or application session ID does not identify an occurrence. See agent evidence pagination.

Authoritative business declarations

For optional include_business_inputs enrichment and accounts business commands, follow Declared account value. It defines the independent financial grants, exact current profile, membership ambiguity and why enriched account rows supply no combined monetary total.