Groups

A group is a collection you associate events with, such as an organization, team, or workspace.

What is a group

A group has a groupId and an optional type such as org, team, service, or workspace. Groups let you attach events to a collection of users rather than a single person.

Attach identity data to a group with vanta.group():

import { Vanta } from '@vanta-dev/node'

const vanta = new Vanta({
  apiKey: process.env.VANTA_API_KEY,
})

await vanta.group({
  groupId: 'org_acme',
  type: 'org',
  name: 'Acme Inc',
  properties: {
    plan: 'enterprise',
    seats: 250,
  },
})

Calling group() emits a $group internal event.

Associating events with a group

Events can carry a groupId directly, so you can attribute a single event to a group:

await vanta.track({
  event: 'api.request',
  groupId: 'org_acme',
  data: {
    endpoint: '/v1/users',
  },
})

Grouping also applies to future events when you call group(), depending on your configuration. The simplest mental model is to attach a groupId to each event you want attributed to that group.

Grouping models

The most common model treats groups as organizations, workspaces, or teams. This gives you multi-tenant analytics: you can answer questions about an entire account instead of digging into individual users. For example, group by workspace to see aggregate usage across everyone in a workspace, then drill into a specific user when something looks off.

Pair grouping with identity to answer “who did what, in which account.” Users give events a person, and groups give them a home.