> ## 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

> Organize users into groups and manage group properties

# 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

<ParamField body="$token" type="string" required>
  Your project token
</ParamField>

<ParamField body="$group_key" type="string" required>
  The group key (e.g., "company", "account\_id")
</ParamField>

<ParamField body="$group_id" type="string" required>
  The unique identifier for this group
</ParamField>

<ParamField body="$set" type="object" required>
  Object containing properties to set
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  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"
        }
      }
    ]'
  ```

  ```python Python theme={null}
  import requests
  import json

  data = [{
      "$token": "YOUR_PROJECT_TOKEN",
      "$group_key": "company",
      "$group_id": "mixpanel_inc",
      "$set": {
          "name": "Mixpanel Inc",
          "industry": "Analytics",
          "employees": 350,
          "plan": "enterprise"
      }
  }]

  response = requests.post(
      'https://api.mixpanel.com/groups',
      data={'data': json.dumps(data)}
  )

  print(response.text)  # Returns 1 for success
  ```

  ```javascript JavaScript theme={null}
  const data = [{
    $token: 'YOUR_PROJECT_TOKEN',
    $group_key: 'company',
    $group_id: 'mixpanel_inc',
    $set: {
      name: 'Mixpanel Inc',
      industry: 'Analytics',
      employees: 350
    }
  }];

  fetch('https://api.mixpanel.com/groups', {
    method: 'POST',
    body: 'data=' + encodeURIComponent(JSON.stringify(data))
  });
  ```
</CodeGroup>

***

## Set Group Property Once

Set properties only if they don't already exist on the group.

### Request Body

<ParamField body="$token" type="string" required>
  Your project token
</ParamField>

<ParamField body="$group_key" type="string" required>
  The group key
</ParamField>

<ParamField body="$group_id" type="string" required>
  The unique identifier for this group
</ParamField>

<ParamField body="$set_once" type="object" required>
  Properties to set only if they don't exist
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  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
        }
      }
    ]'
  ```

  ```python Python theme={null}
  data = [{
      "$token": "YOUR_PROJECT_TOKEN",
      "$group_key": "company",
      "$group_id": "mixpanel_inc",
      "$set_once": {
          "created_date": "2024-01-01",
          "founding_year": 2009
      }
  }]

  response = requests.post(
      'https://api.mixpanel.com/groups',
      data={'data': json.dumps(data)}
  )
  ```
</CodeGroup>

***

## Delete Group Property

Remove specific properties from a group profile.

### Request Body

<ParamField body="$token" type="string" required>
  Your project token
</ParamField>

<ParamField body="$group_key" type="string" required>
  The group key
</ParamField>

<ParamField body="$group_id" type="string" required>
  The unique identifier for this group
</ParamField>

<ParamField body="$unset" type="array" required>
  Array of property names to delete
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  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"]
      }
    ]'
  ```

  ```python Python theme={null}
  data = [{
      "$token": "YOUR_PROJECT_TOKEN",
      "$group_key": "company",
      "$group_id": "mixpanel_inc",
      "$unset": ["temp_field", "old_data"]
  }]

  response = requests.post(
      'https://api.mixpanel.com/groups',
      data={'data': json.dumps(data)}
  )
  ```
</CodeGroup>

***

## Union To List Property

Add values to a list property, ensuring uniqueness.

### Request Body

<ParamField body="$token" type="string" required>
  Your project token
</ParamField>

<ParamField body="$group_key" type="string" required>
  The group key
</ParamField>

<ParamField body="$group_id" type="string" required>
  The unique identifier for this group
</ParamField>

<ParamField body="$union" type="object" required>
  Object with arrays of values to add
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  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"]
        }
      }
    ]'
  ```

  ```python Python theme={null}
  data = [{
      "$token": "YOUR_PROJECT_TOKEN",
      "$group_key": "company",
      "$group_id": "mixpanel_inc",
      "$union": {
          "products": ["analytics", "data-warehouse"],
          "integrations": ["salesforce", "hubspot"]
      }
  }]

  response = requests.post(
      'https://api.mixpanel.com/groups',
      data={'data': json.dumps(data)}
  )
  ```
</CodeGroup>

***

## Remove from List Property

Remove specific values from a list property.

### Request Body

<ParamField body="$token" type="string" required>
  Your project token
</ParamField>

<ParamField body="$group_key" type="string" required>
  The group key
</ParamField>

<ParamField body="$group_id" type="string" required>
  The unique identifier for this group
</ParamField>

<ParamField body="$remove" type="object" required>
  Object with values to remove
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.mixpanel.com/groups \
    --data-urlencode data='[
      {
        "$token": "YOUR_PROJECT_TOKEN",
        "$group_key": "company",
        "$group_id": "mixpanel_inc",
        "$remove": {
          "integrations": "deprecated_tool"
        }
      }
    ]'
  ```

  ```python Python theme={null}
  data = [{
      "$token": "YOUR_PROJECT_TOKEN",
      "$group_key": "company",
      "$group_id": "mixpanel_inc",
      "$remove": {
          "integrations": "deprecated_tool"
      }
  }]

  response = requests.post(
      'https://api.mixpanel.com/groups',
      data={'data': json.dumps(data)}
  )
  ```
</CodeGroup>

***

## Delete Group

Permanently delete a group profile.

### Request Body

<ParamField body="$token" type="string" required>
  Your project token
</ParamField>

<ParamField body="$group_key" type="string" required>
  The group key
</ParamField>

<ParamField body="$group_id" type="string" required>
  The unique identifier for this group
</ParamField>

<ParamField body="$delete" type="string" required>
  Set to empty string (value is ignored)
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.mixpanel.com/groups \
    --data-urlencode data='[
      {
        "$token": "YOUR_PROJECT_TOKEN",
        "$group_key": "company",
        "$group_id": "old_company",
        "$delete": ""
      }
    ]'
  ```

  ```python Python theme={null}
  data = [{
      "$token": "YOUR_PROJECT_TOKEN",
      "$group_key": "company",
      "$group_id": "old_company",
      "$delete": ""
  }]

  response = requests.post(
      'https://api.mixpanel.com/groups',
      data={'data': json.dumps(data)}
  )
  ```
</CodeGroup>

***

## Batch Update Groups

Update multiple groups in a single request.

### Example

<CodeGroup>
  ```python Python theme={null}
  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)
  ```
</CodeGroup>

## Linking Users to Groups

To associate users with groups, send events with group properties:

<CodeGroup>
  ```python Python theme={null}
  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]
  )
  ```
</CodeGroup>

<Note>
  The group key (e.g., "company") must be defined in your project settings under Group Keys before you can use it.
</Note>

## Best Practices

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="Use consistent group identifiers">
    Use the same identifier format across all systems:

    ```python theme={null}
    # Good: Consistent IDs
    "$group_id": "company_12345"

    # Bad: Inconsistent IDs
    # Sometimes "company_12345", sometimes "12345"
    ```
  </Accordion>

  <Accordion title="Store group-level metrics as properties">
    Track aggregate information about the group:

    ```python theme={null}
    {
        "$set": {
            "total_users": 150,
            "monthly_usage": 50000,
            "plan": "enterprise",
            "seats_purchased": 200
        }
    }
    ```
  </Accordion>

  <Accordion title="Update group properties when they change">
    Keep group data in sync with your systems:

    ```python theme={null}
    # When a company upgrades
    update_group({
        "$set": {
            "plan": "enterprise",
            "upgrade_date": "2024-01-15"
        }
    })
    ```
  </Accordion>
</AccordionGroup>

## Common Use Cases

### B2B SaaS Company Analytics

<CodeGroup>
  ```python Python theme={null}
  # 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"
      }
  }
  ```
</CodeGroup>

### Multi-tenant Applications

<CodeGroup>
  ```python Python theme={null}
  # 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"
      }
  }]
  ```
</CodeGroup>