Docs
Data Structure
Events & Properties

Events And Properties

Overview

Events are the core of Mixpanel's Data Model. All events should have an Event Name, a Timestamp of when that event has occurred, and a Distinct ID (Mixpanel's identifier for a user) to tie all events belonging to the same user. Events can optionally have a set of properties, which describes the event in more detail.

  • If you're familiar with databases, events are like tables and properties are like columns.
  • If you're familiar with Google Analytics, events are like hits and properties are like dimensions.

Note: There are a few use cases, such as tracking Ad Spend, in which the event should not be tied to specific users; as such, these events should be sent without a Distinct ID, but this is the exception.

For more information about events refer to the documentation on The Mixpanel Data Model.

Examples

  • A Page Viewed event might have a property called Page URL, which is set to the URL of the page that was viewed.
  • A Signed Up event might have a property called Signup Type, which indicates whether the signup was organic vs referral.
  • A Song Played event might have a property called Song Name, which is set to the name of the song that was played.
  • An Order Completed event might have a property called Items, which is a list of objects, each of which contains details about an item, like its name, category, and price.

Use Cases

You can filter, breakdown, and aggregate your events by their properties to answer more questions:

  • Which pages do users look at before they visit the pricing page?
  • How many sign-ups did I get that were organic vs referral?
  • Which song name is most popular among my users?
  • How many orders contain shoes? What is the sum total price that users paid for shoes in the last month?

Best Practices

Keep Events as Actions

We recommend striking the right balance when defining your events. Events should neither be too broad nor too specific, and should be defined at the level of how you plan to analyse the user's action or behavior. Also keep in mind to use event properties to provide context or details about an event, instead of creating different events to capture similar actions.

For example:

  • If your goal is to analyze at high-level how users traverse through different pages: instead of tracking multiple events Home Page Viewed and Pricing Page Viewed, track a Page Viewed event with a Page Name property set to "/home" or "/pricing". See Tracking Page Views in our Javascript SDK documentation on how to instrument this.

  • If your goal is to track users adding items to a shopping cart: instead of tracking multiple events Add Shirt to Cart, Add Hoodie to Cart, and Add Socks to Cart, track a Add to Cart event with a Item property set to "Shirt", or "Hoodie", or "Socks".

  • If your goal is to track 1 button on a specific screen: instead of tracking multiple events Blue Button Clicked and Checkout Button Clicked, track a Button Clicked event with a Color property set to "Blue" and Button Name set to "Checkout".

  • If your goal is to track different buttons from different user journeys: instead of tracking 1 event Button Clicked with Button Name property set to "Play", or "Profile", or "X", track them as different events Song Played and Profile Updated and Logout with specific properties for each event to provide richer context.

Name Events and Properties Consistently

We recommend having a consistent naming convention for your events and properties:

  • Generally, adopting snake_case for your event and property names tend to be more robust, especially if you plan to export your Mixpanel data to downstream processes such as data warehouses. Do also note that Mixpanel is case-sensitive (eg sign_up_completed vs Sign Up Completed are considered two separate events).

  • Use the (Object) (Verb) format for event names. Like song_played or page_viewed.

  • Mixpanel Lexicon provides a means for you to change an event's or property's display name on the UI (if needed, to make it more user-friendly).

Avoid Creating Events or Property Names Dynamically

For example, don't create an event name like Purchase (11-01-2019). Instead, create an event called Purchase and have some property (eg: Return Date) set to the dynamic value "11-01-2019".

Tip: Learn more best practices around defining your events and properties under our tutorials for Creating a Tracking Plan.

Reserved Event Properties

Mixpanel reserves certain event property names for special processing or for specific system features. These properties, when populated, will affect the way Mixpanel processes your data.

Note: Also refer to the list of Mixpanel Default Properties indicated in our documentation.

Raw NameDisplay NameDescription
token-The project's token when sending data via /track API (opens in a new tab). Not visible via Mixpanel UI reports.
ip-The ip event property is the value to be used for geo location parsing (i.e. $city, $region, and mp_country_code) if ip as param to the /track endpoint (opens in a new tab) has not been set to 1. Our client-side libraries, by default, will set the ip param to 1 so geo location is parsed from the incoming request, but this can be disabled or, if you're implementing from the server-side, you can include the ip event property so it's parsed from it instead of the IP of the incoming request. The ip event property is not stored in Mixpanel.
$bucket / bucket-A reserved property that is hidden from the Mixpanel interface, and will cause other events to not appear in the interface. Do not name any property bucket or $bucket.
$distinct_id / distinct_idDistinct IDMixpanel's internal unique identifier for a user. See Identifying Users.
$device_idDevice IDIn Simplified ID Merge: unique identifier used to track a device while the user is in anynymous state.
$user_idUser IDIn Simplified ID Merge: unique identifier used to track a user across devices when user is in identified state.
$event_nameEvent NameName of the tracked event used in the Mixpanel UI.
$time / timeTime or DateA unix time epoch that is used to determine the time of an event. If no time property is provided, we will use the time when the event arrives at our servers.
$insert_idInsert IDA unique identifier for the event, used to deduplicate events that are accidentally sent multiple times. More details here (opens in a new tab).
$identified_idIdentified IDIn Original ID Merge: Internal Mixpanel property to track the identifier passed into the $identify (opens in a new tab) event.
$anon_idAnonymous IDIn Original ID Merge: Internal Mixpanel property to track the anonymous ID passed into the $identify (opens in a new tab) event.
aliasAliasIn Original ID Merge: Internal Mixpanel property to track the alias passed into the $create_alias (opens in a new tab) event.
$distinct_idsDistinct IdsIn Original ID Merge: Internal Mixpanel property to track the distinct IDs passed into the $merge (opens in a new tab) event.
$distinct_id_before_identityDistinct ID Before IdentityInternal Mixpanel property to track an event's original $distinct_id before it was updated due to identity merging. Used in Original ID Merge and Simplified ID Merge.
$is_reshuffledIs ReshuffledInternal Mixpanel property to denote an event was reshuffled (sets to true if original $distinct_id was updated) due to identity merging. Used in Original ID Merge and Simplified ID Merge.
$failure_descriptionFailure DescriptionIn Original ID Merge: Mixpanel property explaining in detail why identity merging was not executed.
$failure_reasonFailure ReasonIn Original ID Merge: Mixpanel property summarizing why identity merging was not executed.
$identity_failure_reasonIdentity Failure ReasonIn Simplified ID Merge: Mixpanel property summarizing why identity merging was not executed.
mp_original_distinct_idHotshard Original Distinct IDOriginal $distinct_id for an event that was identified as contributing to a hot shard (opens in a new tab).
mp_original_event_nameHotshard Original Event NameOriginal $event_name for an event that was identified as contributing to hot shard (opens in a new tab).
$sourceSourceHidden property used by certain integration partners to denote events were sent by them. Refer to the respective partners under Cohort Sync -> Integrations.
$partner_idPartner IdHidden property used by certain integration partners to denote events were sent by them. Refer to the respective partners under Cohort Sync -> Integrations.
$warehouse_typeWarehouse TypeThe type of the warehouse sync setup to send the event. See Supported Warehouses.
$warehouse_import_idWarehouse Import IDThe ID of the warehouse sync setup to send this event. See Data Warehouse.
$warehouse_import_job_idWarehouse Import Job IDThe internal Mixpanel Job ID of the warehouse sync setup to send this event. See Data Warehouse.
$warehouse_import_run_idWarehouse Import Run IDThe internal Mixpanel Run ID of the warehouse sync setup to send this event. See Data Warehouse.
$duration_sSession Duration (Seconds)The duration between Session Start and Session End events in seconds. See How Sessions Work.
$event_countSession Event CountThe number of events during a session (i.e. Session Start and Session End). This does not include Excluded Events and Hidden Events in Lexicon. See How Sessions Work.
$origin_startSession Start Event NameThe original event name that triggered Session Start event. See How Sessions Work.
$origin_endSession End Event NameThe original event name that triggered Session End event. See How Sessions Work.

FAQ

What types of data can I send as properties?

Mixpanel accepts arbitrary JSON as properties, including strings, numbers, booleans, lists, and objects. See our API docs (opens in a new tab) for more details.

What are the limits of events and properties?

We don't have a limit on the total number of events you can send to Mixpanel, but it will factor into your pricing (opens in a new tab).

We have a soft limit of 2000 distinct event names in a 30 day window. If you send more event names, we'll still ingest them, but those event names will not be indexed and will not appear in our autocomplete menus.

Each event can have up to 2000 properties. Event property names can be at most 255 characters in length (longer names are truncated). Event property values are limited based on data type, refer to these limits under Supported Data Types.

Note: while events can have up to 2000 properties and batches of events can have up to 2000 events per ingestion batch, some libraries might default to sending the data through the GET protocol which would have a much lower size limit since the information is appended to the URL. If you are hitting the limits on the size of the request, first verify if the method being used is GET and can be switched to POST.

Was this page useful?