Groups

Organize users into groups and manage group properties

POST /groups

Groups

cURL

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>"
}
'

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

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

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

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

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

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

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

Python

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:

Python

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 products
• organization: For enterprise customers
• team: For team-based features
• workspace: 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

Python

# 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": "[e-mail]",
        "company": "acme_corp",
        "feature": "advanced_analytics"
    }
}

Multi-tenant Applications

Python

# 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"
    }
}]