Groups

A group is a set of events that share the same value for one property you nominate, like a team id, a server name, or an account id. You tell TopStats which property to roll up on, and every event carrying that property joins the group named by its value.

Think of it as the "who is this for?" layer above the individual person. A single player belongs to a clan. A single seat belongs to a company. A single request belongs to a shard. Groups let you count and follow those containers instead of the individuals inside them.

A group is not an actor

This is the distinction that matters, and it is the reason the two live on separate pages.

An actor is who an event belongs to. You set it with the reserved _actor field, it is a first-class part of the event payload, and TopStats always knows about it.

A group is what an event belongs to. It is an ordinary property inside your own properties object, and TopStats only treats it as a grouping once you say which key to use.

One event can carry both at once, and usually should. _actor: "user_123" with properties.team_id: "team_42" says this was done by Ada, on behalf of team 42. The Actors page follows Ada. The Groups page follows team 42.

What a group key is made of

A group key is the small piece of configuration that tells TopStats which property to roll up on. It has three parts.

A group key is set for the whole workspace, so it applies to every environment in it, production and development included. The environment picker in Settings only changes which stream is searched for candidate properties, not where the key applies once it is saved.

How an event joins a group

There is no separate call and no reserved field. An event joins a group by carrying the registered property, with the group id as its value.

Say you registered team_id as your group key. This event belongs to group team_42:

{
  "name": "match_end",
  "properties": {
    "team_id": "team_42",
    "map": "desert"
  },
  "_actor": "user_123"
}

Sent the same way from anywhere:

curl -X POST https://topstats.gg/v1/events \
  -H "Authorization: Bearer ts_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "match_end",
    "properties": { "team_id": "team_42", "map": "desert" },
    "_actor": "user_123"
  }'

Two rules decide whether an event counts toward a group:

• The event has to carry the key. An event with no team_id is not in any group and is skipped by everything on this page.
• The value has to be non-empty. "team_id": "" is treated the same as not sending it at all.

Group ids are matched exactly and are case-sensitive, so Team_42 and team_42 are two different groups. Pick a stable id and stick to it, the same way you would with an _actor.

Why you would use one

Reach for a group whenever the thing you actually care about is bigger than one person.

• Per-account health. You sell to companies, not seats. Ranking accounts by activity tells you which ones are alive and which have gone quiet, which counting individual users never shows you.
• Infrastructure slices. Roll up by server, shard, or region and the Groups page becomes a ranked view of where your load is really going.
• Team and guild activity. In a game, clan_id turns a flat pile of match events into a leaderboard of which clans are actually playing.
• Honest funnel and retention numbers. A team of ten where one person converts is a converted team, not a 10% conversion. Counting by group says so.

A concrete example. A game sends a match_end event on every match, each with clan_id in properties and the player in _actor. Register clan_id as the group key and the Groups page ranks clans by match volume, with the busiest at the top and the ones that have gone silent falling down the list. Switch a retention grid to count by group and you find out whether clans keep playing week after week, which is a very different question from whether individual players do.

Registering a group key

Group keys live in Settings, in the Group keys section. Until you add one, the Groups page has nothing to show and offers you a link straight here.

The Groups page

Groups in the main navigation shows your events rolled up by the group key, ranked by activity. At the top you get three controls:

• Environment - which stream to read: production, development, or any environment you have added.
• Time range - 1h, 24h, 7d (the default), 30d, or 90d.
• Group key - only shown when you have registered more than one. It starts on the default key.

Below that, two summary tiles give you the number of groups listed and their combined event count, then a search box and the ranked list itself.

Each row in the list shows the group id, how long ago it was last seen, and its event count, with a bar behind it sized against the busiest group so you can see the shape of the distribution at a glance. Groups are ordered by event count, highest first, and up to 50 are listed. Search filters the loaded list by substring, case-insensitively, so typing eu- narrows a server list to the European shards.

The group detail pane

Select a group and the pane on the right fills in with everything TopStats knows about it in the selected range. The busiest group is selected for you when the page loads, so the pane is never empty.

Every row in Recent activity shows the event name, its source label if it has one, and the time it happened. Expand a row and you get that event's payload, with all of its properties, so you can see the full context without leaving the page. List properties are shown as their values together.

Counting funnels and retention by group

Registering a group key also changes what you can do on a dashboard. Funnel and Retention widgets both have a Count setting in the widget builder with two options:

The default is Actor, and existing widgets are unaffected until you change them.

Switching to Group swaps the unit the widget counts, and that is the whole change. In a funnel, a group reaches a step when any event from that group fires it in the right order inside the conversion window, so one busy member is enough to carry the whole group through. In a retention grid, a group is placed in the cohort of the period it first fired the cohort event, and it counts as retained in a later period when any of its events fire the return event then.

The practical effect is that counts get smaller and conversion rates usually get higher, because you are counting containers rather than people. A funnel where 1,000 users convert out of 10,000 might be 200 teams out of 300, and those two numbers tell you very different things.

Two things to know before you switch:

• Group counting always uses the workspace default group key. It is not chosen per widget. If you change which key is the default, every group-grained funnel and retention widget follows it.
• Events without the key are excluded. With Actor, the widget reads every matching event. With Group, an event that does not carry the group key, or carries an empty value, drops out of the widget completely.

Who can manage group keys

Group keys sit with the rest of your workspace configuration in Settings, and any member of a paid workspace can view the Groups page and add or remove a group key. Because a group key changes what every group-grained funnel and retention widget counts, treat swapping the default as a workspace-wide change rather than a personal preference. For how roles work everywhere else, see Roles and permissions.

API endpoints

The Groups pages are driven by these endpoints, all under https://topstats.gg. Every one of them needs a signed-in session on a paid workspace, and the three GET endpoints all take environment and timeRange as required query parameters.

A few details worth knowing:

• GET /v1/groups accepts an optional propKey to read a group key other than the default, and an optional limit between 1 and 200, defaulting to 50.
• GET /v1/groups/:groupKey accepts the same optional propKey. It returns 404 when the group has no events in the selected range.
• With no group key registered, GET /v1/groups returns an empty list rather than an error.
• A free workspace gets 402 from all of them. See Limits and errors.

Related pages