Skip to main content
POST
/
engage
User Profiles
curl --request POST \
  --url https://api.mixpanel.com/engage \
  --header 'Content-Type: application/json' \
  --data '
{
  "$token": "<string>",
  "$distinct_id": "<string>",
  "$set": {},
  "$set_once": {},
  "$add": {},
  "$union": {},
  "$append": {},
  "$remove": {},
  "$unset": [
    {}
  ],
  "$delete": "<string>",
  "$ignore_alias": true
}
'

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.

​
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.
​
ip
string
If set to 1, uses the request IP for geolocation
​
strict
string
Enable strict mode for validation
​
verbose
string
Return detailed response instead of 1 or 0

​
Request Body

​
$token
string
required
Your project token
​
$distinct_id
string
required
The unique identifier for the user
​
$set
object
required
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": "user@example.com",
        "$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

​
$token
string
required
Your project token
​
$distinct_id
string
required
The unique identifier for the user
​
$set_once
object
required
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

​
$token
string
required
Your project token
​
$distinct_id
string
required
The unique identifier for the user
​
$add
object
required
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

​
$token
string
required
Your project token
​
$distinct_id
string
required
The unique identifier for the user
​
$union
object
required
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

​
$token
string
required
Your project token
​
$distinct_id
string
required
The unique identifier for the user
​
$append
object
required
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

​
$token
string
required
Your project token
​
$distinct_id
string
required
The unique identifier for the user
​
$remove
object
required
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

​
$token
string
required
Your project token
​
$distinct_id
string
required
The unique identifier for the user
​
$unset
array
required
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

​
$token
string
required
Your project token
​
$distinct_id
string
required
The unique identifier for the user
​
$delete
string
required
Set to empty string or null (value is ignored)
​
$ignore_alias
boolean
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": "user1@example.com"}
    },
    {
        "$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:
PropertyDescription
$emailUser’s email address
$nameUser’s full name
$first_nameUser’s first name
$last_nameUser’s last name
$phoneUser’s phone number
$avatarURL to user’s avatar image
$createdProfile creation time (set automatically)
$last_seenLast activity time (set automatically)
You can use custom properties alongside reserved properties. Just avoid using the $ prefix for your custom properties.

​
Best Practices

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
  • 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"
Avoid storing thousands of items in list properties. Consider:
  • Using counts instead of full lists
  • Storing only recent items
  • Moving historical data to events

Build docs developers (and LLMs) love

Get started for freeTalk to us