Conversation
Ports the content from mixpanel/docs-legacy#2647 into the Mintlify docs site, converting Nextra syntax to Mintlify components. - Rewrite group-analytics.mdx as an overview that forks between the two models, with a comparison table - Add hierarchical-groups.mdx covering the $company_id/$user_id composite identity model, implementation, and FAQ - Add standard-group-analytics.mdx, absorbing the implementation and FAQ pages - Redirect the retired implementation and FAQ URLs to Standard Groups Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
 |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| </Note> | ||
|
|
||
| Group level: | ||
|
|
||
| ``` |
There was a problem hiding this comment.
Standard Groups do not replace an event’s user distinct_id with the group ID, as this page later confirms. Labeling <group_id> as distinct_id can lead implementers to send group IDs as user identities, combining unrelated users and corrupting user-level analysis. Describe this as the group’s analysis identifier instead.
Knowledge Base Used: Identity, profiles, and groups
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
| To create or update company profiles via the HTTP API, use the `/groups` endpoint. There are three key values that must be set in order to properly set profiles for Hierarchical Groups (outside of `$set`) — `$group_key`, `$group_id`, and `$company_id`. | ||
|
|
||
| - `$group_key` — the name of the group key you want to set the profile properties to (`$company_id`, `$user_id`, etc.) | ||
| - `$group_id` — the actual value of the group key you want to set those properties on (`acme`, `user_123`, etc.) | ||
| - `$company_id` — the value of the parent `$company_id` associated with this child entity (`acme`) |
There was a problem hiding this comment.
The new instructions require $company_id for hierarchical /groups requests and a Company ID mapping for warehouse Group Tables, but the corresponding public schemas expose neither field. This leaves generated references and clients unable to represent the required company scope. Update those API contracts alongside this page, or clarify the supported configuration path. The same mismatch appears in the Group Table instructions at lines 249–253.
Knowledge Base Used: Identity, profiles, and groups
Co-authored-by: mherrman <24963335+mherrman@users.noreply.github.com>
Co-authored-by: mherrman <24963335+mherrman@users.noreply.github.com>
- Reword the frontmatter `description` so the reserved-property names no longer render as KaTeX math (the `$company_id`/`$user_id` `$…$` pair was garbling the page subtitle). - Demote the "Groups HTTP API" heading from H3 to H4 so it nests under "Updating Group Profiles" alongside "Warehouse Connector: Profiles". Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JwB62afN5wxzrfpMvKPuJV
|
|
||
| Identity Management works only on the user level. In Hierarchical Groups, the canonical user identity is determined by the composite of the `$company_id` and `$user_id` values as soon as one of those values is set (so ideally they are set together at the same time). Events sent without `$company_id` and `$user_id` that have a `$device_id` value can later be merged to a canonical user identifier by having `$company_id` and `$user_id` set alongside the `$device_id` value on an event. | ||
|
|
||
| Merging the `$device_id` to the canonical `$company_id` and `$user_id` composite means that all events going forward and historically attributed to the `$device_id` would be merged to the composite identifier, similar to how Simplified ID Merge works outside of Hierarchical Groups. At present the merged events are only visible in the User level activity feed. |
There was a problem hiding this comment.
At present the merged events are only visible in the User level activity feed.
This is something that I want to confirm with eng to see if this is intention and will be the case upon GA
|
|
||
| Hierarchical Groups can only be implemented via Data Warehouse Connectors or directly via the HTTP APIs. The groups methods in Mixpanel's SDKs only support standard groups. | ||
|
|
||
| ### Group Keys in Project Settings |
There was a problem hiding this comment.
need to confirm its been changed such that the defaults ($company_id and $user_id) still need to be set as group props manually. iirc we intended to have those be set automatically as special
| curl --request POST \ | ||
| --url 'https://api.mixpanel.com/import?strict=1&project_id=YOUR_PROJECT_ID' \ | ||
| --header 'Content-Type: application/json' \ | ||
| --header 'accept: application/json' \ | ||
| --header 'authorization: Basic AUTH_HERE' \ | ||
| --data '[ | ||
| { | ||
| "event": "Feature Used", | ||
| "properties": { | ||
| "time": 1690000000, | ||
| "$insert_id": "unique_event_id", | ||
| "$company_id": "acme", | ||
| "$user_id": "alice", | ||
| "feature_name": "dashboard" | ||
| } | ||
| } | ||
| ]' | ||
| ``` |
There was a problem hiding this comment.
need to verify how we want to present distinct_id here. i don't think it has any impact on what the resultant id is for the user in MP if $user_id and $company_id are present but i also dont think you can technically send an event to /import API in strict mode without that property present?
| "time": 1690000000, | ||
| "$insert_id": "unique_event_id", | ||
| "$company_id": "acme", | ||
| "$user_id": "alice", | ||
| "feature_name": "dashboard" |
There was a problem hiding this comment.
This strict Import API example omits distinct_id, even though the preceding instructions and the Import API schema require it. Readers who copy this request will receive a validation error instead of ingesting the event. Include a placeholder distinct_id that Hierarchical Groups can override.
| "time": 1690000000, | |
| "$insert_id": "unique_event_id", | |
| "$company_id": "acme", | |
| "$user_id": "alice", | |
| "feature_name": "dashboard" | |
| "time": 1690000000, | |
| "$insert_id": "unique_event_id", | |
| "distinct_id": "placeholder", | |
| "$company_id": "acme", | |
| "$user_id": "alice", | |
| "feature_name": "dashboard" |
Knowledge Base Used: Identity, profiles, and groups
|
Want your agent to iterate on Greptile's feedback? Try greploops. |
Why
Ports the Hierarchical Groups content from mixpanel/docs-legacy#2647 into the new docs site. Group Analytics now has two distinct data models — Hierarchical and Standard — and the current docs only describe the Standard one, so B2B customers have no documentation for the
$company_id/$user_idmodel.What
group-analytics.mdxas an overview that forks between the two models, with a comparison table for choosing between themhierarchical-groups.mdxcovering composite identity, prerequisites, data model, identity management, implementation (Import API + Warehouse Connectors + Groups HTTP API), and FAQstandard-group-analytics.mdx, absorbing the retired Implementation and FAQ pagesgroup-analytics-implementation.mdxandgroup-analytics-faq.mdx, withdocs.jsonredirects to Standard Groups so existing URLs don't 404Test plan
<Tabs>SDK block and the comparison tabledocs.jsonparses as valid JSON, all 10 referenced images exist, and no page in the repo links to the two deleted filesNotes for reviewers
One open content question, inherited from the source PR and left in deliberately for a reviewer to resolve:
standard-group-analytics.mdxstates "up to 5 group keys per project" under Overview, but "up to 3 group keys, Enterprise can increase to 6 for an additional fee" under Limits. These contradict each other — please confirm which is correct.Deviations from the legacy PR:
#identity_managment→#identity-management) and an FAQ list that skipped from 1 to 3.#setup-b2b-company-keylinks to the Standard Groups page, where that section now lives.group_analytics_data_model.pngare dropped, mirroring the legacy PR.group_analytics_data_model.pngis now unreferenced.hierarchical-groupsis.mdxrather than the source's.md, to match repo convention.Conversions applied: H1 → YAML frontmatter;
<Callout type="info">→<Note>; the irreversible-setup blockquote →<Warning>;<Tabs items={[…]}><Tabs.Tab>→<Tabs><Tab title="…">; images →/images/…in<Frame>; relative links → absolute;_meta.ts→ thenavigationblock indocs.json.🤖 Generated with Claude Code