Skip to main content
POST
/
groups
Groups
curl --request POST \
  --url https://api.mixpanel.com/groups \
  --header 'Content-Type: application/json' \
  --data '
{
  "$token": "<string>",
  "$group_key": "<string>",
  "$group_id": "<string>",
  "$set": {},
  "$set_once": {},
  "$unset": [
    {}
  ],
  "$union": {},
  "$remove": {},
  "$delete": "<string>"
}
'

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mixpanel/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
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

​
$token
string
required
Your project token
​
$group_key
string
required
The group key (e.g., “company”, “account_id”)
​
$group_id
string
required
The unique identifier for this group
​
$set
object
required
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

​
$token
string
required
Your project token
​
$group_key
string
required
The group key
​
$group_id
string
required
The unique identifier for this group
​
$set_once
object
required
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

​
$token
string
required
Your project token
​
$group_key
string
required
The group key
​
$group_id
string
required
The unique identifier for this group
​
$unset
array
required
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

​
$token
string
required
Your project token
​
$group_key
string
required
The group key
​
$group_id
string
required
The unique identifier for this group
​
$union
object
required
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

​
$token
string
required
Your project token
​
$group_key
string
required
The group key
​
$group_id
string
required
The unique identifier for this group
​
$remove
object
required
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

​
$token
string
required
Your project token
​
$group_key
string
required
The group key
​
$group_id
string
required
The unique identifier for this group
​
$delete
string
required
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

Before sending group data, configure your group keys in Project Settings > Group Keys. Common examples:
  • company: For B2B SaaS products
  • organization: For enterprise customers
  • team: For team-based features
  • workspace: For workspace-based products
Use the same identifier format across all systems:
# Good: Consistent IDs
"$group_id": "company_12345"

# Bad: Inconsistent IDs
# Sometimes "company_12345", sometimes "12345"
Track aggregate information about the group:
{
    "$set": {
        "total_users": 150,
        "monthly_usage": 50000,
        "plan": "enterprise",
        "seats_purchased": 200
    }
}
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": "user@acme.com",
        "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"
    }
}]

Build docs developers (and LLMs) love

Get started for freeTalk to us