Dashboard Manual Changelog Pricing Use Cases
Manual

Groups

A group is a collective your users belong to in your product: an organization, company, team, workspace, or whatever your app calls it. Dregs records the groups your app reports, keeps each one's data, and tracks which identities are members, so you can see a whole customer account at once instead of one user at a time.

What Is a Group

Most SaaS apps already have at least one kind of collective, and often two: a company that pays, and teams or workspaces inside it. Dregs uses your existing IDs and names for these rather than inventing its own. Groups are optional. Send one when the user is acting inside it, and Dregs records it alongside the identity.

A group has four parts:

  • Type: your own word for the kind of group, such as organization, team, or clinic.
  • ID: the identifier your system already uses for it, up to 64 characters.
  • Data: optional key-value pairs describing it, such as its name or plan.
  • Members: the identities that belong to it.

A group is identified by its type and ID together, so team 42 and project 42 are different groups.

Group Types

When you leave the type out, it is organization. Otherwise, use whatever word your product uses. An event can carry one group of each type, such as the user's company and the team within it.

Dregs stores each type in lower_snake_case, so ParentCompany, parent-company, and Parent Company are all the type parent_company, shown as PARENT COMPANY in the dashboard. A type must start with a letter and normalize to at most 32 letters, digits, and underscores.

Each account can use up to 10 types. Real apps have a handful, so the limit mostly catches a mistake such as sending group IDs in the type field. On an event, a group whose type is invalid, or would be an eleventh type, is ignored, and the rest of the event is still recorded.

Sending Groups from the Browser

In the browser, call dregs.group() once your app knows the current group, and again when the user switches. The tracker remembers one group per type and attaches all of them to every later event: 

dregs.group('organization', 'org_678', {name: 'Acme Inc', plan: 'enterprise'});
dregs.group('team', 'team_42', {name: 'Payments'});

If the user is already identified, calling group() sends a dregs_group event so the membership is recorded right away. Pass null as the ID to clear the group of that type, for example when the user leaves a workspace view. For the full parameter list, see Tracking.

Sending Groups from Your Backend

The server SDKs take a list of groups on track(), each with a type, an ID, and optional data: 

# Python
client.track(
    "user.login",
    identity="user_12345",
    groups=[
        {"type": "organization", "id": "org_678", "data": {"name": "Acme Inc", "plan": "enterprise"}},
        {"type": "team", "id": "team_42", "data": {"name": "Payments"}},
    ],
)

Over plain HTTP, add a groups array to the body of POST /api/events, next to the identity: 

{
  "type": "login",
  "identity": {"id": "user_12345"},
  "groups": [
    {"type": "organization", "id": "org_678", "data": {"name": "Acme Inc", "plan": "enterprise"}},
    {"type": "team", "id": "team_42", "data": {"name": "Payments"}}
  ],
  "data": {}
}

How Groups Are Created and Updated

The first event that mentions a group creates it. Later events merge their data into it, the same way identity data accumulates, so an event can carry just the type and id. Dregs also records which groups each event was sent with, so a group's detail page can show its recent activity.

The group's display name comes from a name field, or from any field you have mapped to Organization Name in Settings, Mappings. If your app calls it company_name or workspace_title, map that field once rather than renaming it in your code.

You can also manage groups directly through the REST API: POST /api/groups creates a group or merges data into an existing one, PATCH /api/groups/{type}/{id} merges new attributes into it, and DELETE /api/groups/{type}/{id} deletes it along with its memberships. Deleting a group keeps its member identities and their events.

Group Membership

When an event carries both an identity and groups, that identity becomes a member of each group. An identity can belong to any number of groups, which matches users who sit on more than one team or work for more than one client.

Events only ever add members. When a user leaves a group, remove them with DELETE /api/groups/{type}/{id}/identities/{identityId}. To add a member without sending an event, for example while backfilling existing accounts, use PUT /api/groups/{type}/{id}/identities/{identityId}. Both the group and the identity must already exist.

Groups in the Dashboard

The Groups page lists every group with its ID, name, type, member count, and when it was first and last seen. Search it by group ID or name, or filter it by type or by identity to see the groups one user belongs to.

A group's detail page shows its data, the identities that belong to it with their scores, and its recent events. That makes it the quickest way to review a whole customer account, such as a workspace on a free trial whose members all scored low on Uniqueness.

An identity's detail page links to the groups it belongs to. On the Identities and Events pages, the group: and groupType: search filters narrow results to a single group, as in group:team_42 groupType:team. When groupType is omitted, it is organization. For more on the dashboard, see Dashboard.

Groups in the API and AI Agents

The REST API lists and reads groups at GET /api/groups and GET /api/groups/{type}/{id}. To list a group's members, filter identities by it: GET /api/identities?group=team_42&groupType=team. Events take the same filter.

AI agents connected through the Dregs MCP server can read groups with list_groups and get_group, so you can ask an agent to review a suspicious workspace's members without opening the dashboard.

Groups and Related Identities

Groups are what your application reports about its users. They are separate from the related identities Dregs discovers on its own from shared devices, IP addresses, and similar names or emails. A group tells you that two users belong to the same account in your product, and a relationship tells you they may be the same person or working together.

Groups are not scored. Each member is still scored as an individual identity, and membership in a group does not raise or lower anyone's scores.

← Identities
Devices →