User Profiles
User profiles store persistent information about your users. Use the Engage API to create and update user profiles with various operations.
Base URL
https://api.mixpanel.com/engage
Authentication
User profile updates use your project token for authentication.
Set Property
Set one or more properties on a user profile. Creates the profile if it doesn’t exist, or updates existing properties.
If set to 1, uses the request IP for geolocation
Enable strict mode for validation
Return detailed response instead of 1 or 0
Request Body
The unique identifier for the user
Object containing property names and values to set
Example
curl https://api.mixpanel.com/engage \
--data-urlencode data='[
{
"$token": "YOUR_PROJECT_TOKEN",
"$distinct_id": "user123",
"$set": {
"$email": "[email protected]",
"$name": "John Doe",
"plan": "premium",
"credits": 100
}
}
]'
Set Property Once
Set properties only if they don’t already exist. Useful for properties like “First Login Date” or “Signup Source”.
Request Body
The unique identifier for the user
Object containing properties to set only if they don’t exist
Example
curl https://api.mixpanel.com/engage \
--data-urlencode data='[
{
"$token": "YOUR_PROJECT_TOKEN",
"$distinct_id": "user123",
"$set_once": {
"first_login": "2024-01-15",
"signup_source": "google_ads",
"referrer": "friend_user456"
}
}
]'
Increment Numerical Property
Increment or decrement numerical properties. Use negative values to decrement.
Request Body
The unique identifier for the user
Object with property names and numerical values to add. Use negative values to subtract.
Example
curl https://api.mixpanel.com/engage \
--data-urlencode data='[
{
"$token": "YOUR_PROJECT_TOKEN",
"$distinct_id": "user123",
"$add": {
"login_count": 1,
"credits": 50,
"failed_attempts": -1
}
}
]'
If the property doesn’t exist, it will be created and set to the specified value (adding to 0).
Union To List Property
Add values to a list property, ensuring each value appears only once.
Request Body
The unique identifier for the user
Object with property names and arrays of values to add
Example
curl https://api.mixpanel.com/engage \
--data-urlencode data='[
{
"$token": "YOUR_PROJECT_TOKEN",
"$distinct_id": "user123",
"$union": {
"favorite_genres": ["action", "comedy"],
"visited_pages": ["homepage", "pricing"],
"used_features": ["export", "analytics"]
}
}
]'
Append to List Property
Append values to a list property. Unlike union, this allows duplicate values.
Request Body
The unique identifier for the user
Object with property names and values to append
Example
curl https://api.mixpanel.com/engage \
--data-urlencode data='[
{
"$token": "YOUR_PROJECT_TOKEN",
"$distinct_id": "user123",
"$append": {
"purchase_history": {"item": "Premium Plan", "date": "2024-01-15"},
"activity_log": "Logged in from mobile"
}
}
]'
Remove from List Property
Remove specific values from a list property.
Request Body
The unique identifier for the user
Object with property names and values to remove
Example
curl https://api.mixpanel.com/engage \
--data-urlencode data='[
{
"$token": "YOUR_PROJECT_TOKEN",
"$distinct_id": "user123",
"$remove": {
"favorite_genres": "horror",
"interests": "deprecated_feature"
}
}
]'
Delete Property
Permanently remove properties from a user profile.
Request Body
The unique identifier for the user
Array of property names to delete
Example
curl https://api.mixpanel.com/engage \
--data-urlencode data='[
{
"$token": "YOUR_PROJECT_TOKEN",
"$distinct_id": "user123",
"$unset": ["temp_token", "session_id", "cache_data"]
}
]'
Delete Profile
Permanently delete a user profile and all its properties.
Request Body
The unique identifier for the user
Set to empty string or null (value is ignored)
Set to true to delete only this specific distinct_id without following alias chains
Example
curl https://api.mixpanel.com/engage \
--data-urlencode data='[
{
"$token": "YOUR_PROJECT_TOKEN",
"$distinct_id": "user123",
"$delete": "",
"$ignore_alias": false
}
]'
Deleting a profile is permanent and cannot be undone. Use with caution.
Batch Update
Send multiple profile updates in a single request. You can mix different operations.
Example
data = [
{
"$token": "YOUR_PROJECT_TOKEN",
"$distinct_id": "user123",
"$set": {"$email": "[email protected]"}
},
{
"$token": "YOUR_PROJECT_TOKEN",
"$distinct_id": "user456",
"$add": {"login_count": 1}
},
{
"$token": "YOUR_PROJECT_TOKEN",
"$distinct_id": "user789",
"$unset": ["temp_data"]
}
]
response = requests.post(
'https://api.mixpanel.com/engage',
data={'data': json.dumps(data)}
)
Reserved Properties
Mixpanel reserves certain property names (prefixed with $) for special purposes:
| Property | Description |
|---|
$email | User’s email address |
$name | User’s full name |
$first_name | User’s first name |
$last_name | User’s last name |
$phone | User’s phone number |
$avatar | URL to user’s avatar image |
$created | Profile creation time (set automatically) |
$last_seen | Last activity time (set automatically) |
You can use custom properties alongside reserved properties. Just avoid using the $ prefix for your custom properties.
Best Practices
Use $set_once for immutable properties
Properties like signup date or first referrer should use $set_once to prevent overwriting:"$set_once": {
"signup_date": "2024-01-15",
"first_referrer": "google.com"
}
Update multiple profiles in a single request for better performance:updates = []
for user in users:
updates.append(create_profile_update(user))
# Send in batches of 2000
Use appropriate data types
- Numbers for metrics:
"credits": 100
- Strings for categories:
"plan": "premium"
- Lists for collections:
"interests": ["tech", "gaming"]
- ISO dates for timestamps:
"last_purchase": "2024-01-15T10:30:00Z"
Keep list properties manageable
Avoid storing thousands of items in list properties. Consider:
- Using counts instead of full lists
- Storing only recent items
- Moving historical data to events