Groups Groups allow you to organize users into entities like companies, accounts, or organizations. Group analytics let you analyze behavior at the group level.
Base URL https://api.mixpanel.com/groups
Authentication Use your project token for authentication.
Set Group Property Update or add properties to a group profile. Creates the group if it doesn’t exist.
Request Body The group key (e.g., “company”, “account_id”)
The unique identifier for this group
Object containing properties to set
Example curl https://api.mixpanel.com/groups \ --data-urlencode data='[ { "$token": "YOUR_PROJECT_TOKEN", "$group_key": "company", "$group_id": "mixpanel_inc", "$set": { "name": "Mixpanel Inc", "industry": "Analytics", "employees": 350, "plan": "enterprise" } } ]'
Set Group Property Once Set properties only if they don’t already exist on the group.
Request Body The unique identifier for this group
Properties to set only if they don’t exist
Example curl https://api.mixpanel.com/groups \ --data-urlencode data='[ { "$token": "YOUR_PROJECT_TOKEN", "$group_key": "company", "$group_id": "mixpanel_inc", "$set_once": { "created_date": "2024-01-01", "founding_year": 2009 } } ]'
Delete Group Property Remove specific properties from a group profile.
Request Body The unique identifier for this group
Array of property names to delete
Example curl https://api.mixpanel.com/groups \ --data-urlencode data='[ { "$token": "YOUR_PROJECT_TOKEN", "$group_key": "company", "$group_id": "mixpanel_inc", "$unset": ["temp_field", "old_data"] } ]'
Union To List Property Add values to a list property, ensuring uniqueness.
Request Body The unique identifier for this group
Object with arrays of values to add
Example curl https://api.mixpanel.com/groups \ --data-urlencode data='[ { "$token": "YOUR_PROJECT_TOKEN", "$group_key": "company", "$group_id": "mixpanel_inc", "$union": { "products": ["analytics", "data-warehouse"], "integrations": ["salesforce", "hubspot"] } } ]'
Remove from List Property Remove specific values from a list property.
Request Body The unique identifier for this group
Object with values to remove
Example curl https://api.mixpanel.com/groups \ --data-urlencode data='[ { "$token": "YOUR_PROJECT_TOKEN", "$group_key": "company", "$group_id": "mixpanel_inc", "$remove": { "integrations": "deprecated_tool" } } ]'
Delete Group Permanently delete a group profile.
Request Body The unique identifier for this group
Set to empty string (value is ignored)
Example curl https://api.mixpanel.com/groups \ --data-urlencode data='[ { "$token": "YOUR_PROJECT_TOKEN", "$group_key": "company", "$group_id": "old_company", "$delete": "" } ]'
Batch Update Groups Update multiple groups in a single request.
Example import requests import json data = [ { "$token" : "YOUR_PROJECT_TOKEN" , "$group_key" : "company" , "$group_id" : "company_1" , "$set" : { "plan" : "enterprise" } }, { "$token" : "YOUR_PROJECT_TOKEN" , "$group_key" : "company" , "$group_id" : "company_2" , "$set" : { "plan" : "professional" } }, { "$token" : "YOUR_PROJECT_TOKEN" , "$group_key" : "company" , "$group_id" : "company_3" , "$set" : { "status" : "active" } } ] response = requests.post( 'https://api.mixpanel.com/groups' , data = { 'data' : json.dumps(data)} ) print (response.text)
Linking Users to Groups To associate users with groups, send events with group properties:
import requests import uuid import time # Track event with group association event = { "event" : "Purchase" , "properties" : { "time" : int (time.time()), "distinct_id" : "user123" , "$insert_id" : str (uuid.uuid4()), "company" : "mixpanel_inc" , # Links user to group "amount" : 99.99 } } response = requests.post( 'https://api.mixpanel.com/import' , auth = ( 'SERVICE_ACCOUNT' , 'SECRET' ), params = { 'project_id' : 'PROJECT_ID' , 'strict' : '1' }, json = [event] )
The group key (e.g., “company”) must be defined in your project settings under Group Keys before you can use it.
Best Practices
Define group keys in project settings
Before sending group data, configure your group keys in Project Settings > Group Keys . Common examples:
company: For B2B SaaS productsorganization: For enterprise customersteam: For team-based featuresworkspace: For workspace-based products
Use consistent group identifiers
Use the same identifier format across all systems: # Good: Consistent IDs "$group_id" : "company_12345" # Bad: Inconsistent IDs # Sometimes "company_12345", sometimes "12345"
Store group-level metrics as properties
Track aggregate information about the group: { "$set" : { "total_users" : 150 , "monthly_usage" : 50000 , "plan" : "enterprise" , "seats_purchased" : 200 } }
Update group properties when they change
Keep group data in sync with your systems: # When a company upgrades update_group({ "$set" : { "plan" : "enterprise" , "upgrade_date" : "2024-01-15" } })
Common Use Cases B2B SaaS Company Analytics # Set up company profile data = [{ "$token" : "YOUR_PROJECT_TOKEN" , "$group_key" : "company" , "$group_id" : "acme_corp" , "$set" : { "name" : "Acme Corporation" , "industry" : "Technology" , "employees" : 500 , "plan" : "enterprise" , "mrr" : 5000 , "seats" : 100 } }] # Track user action with company association event = { "event" : "Feature Used" , "properties" : { "distinct_id" : "[email protected] " , "company" : "acme_corp" , "feature" : "advanced_analytics" } }
Multi-tenant Applications # Track workspace-level metrics data = [{ "$token" : "YOUR_PROJECT_TOKEN" , "$group_key" : "workspace" , "$group_id" : "ws_12345" , "$set" : { "name" : "Marketing Team" , "members_count" : 15 , "storage_used_gb" : 250 , "plan" : "professional" } }]