Events

An event is the core unit of data in PostHog. It represents an interaction a user has with your app or website. Examples include button clicks, pageviews, query completions, and signups.

Events consist of:

1. An event name like $pageview or query completed. Events starting with $ are PostHog defaults.

2. A distinct_id which is a unique identifier for person, commonly a uuidv7 value like 018daf23-89b3-7cf8-a4f1-94064c96df90

3. A timestamp in ISO 8601 format, which is the time the event occurred like 2024-05-22T17:09:29.220Z. This is most commonly now(), but can also be in the past.

4. properties, which are additional data like color or $current_url. Properties starting with $ are PostHog defaults.

You can capture custom events using any of our SDKs or our API. PostHog's client-side SDKs, like JavaScript Web and React Native, can also autocapture events for you.

You can view recent events in your activity tab, which automatically updates every 30 seconds for a live view of activity in your app.

How events power PostHog

PostHog is event-based, meaning much of the functionality is triggered through events. Much of this is handled (and made nicer) by our SDKs, but under the hood, it is largely events. For example:

• Changing person properties using $set and $unset properties.

• Identifying an anonymous user with the $identify event.

• Connecting two users with the $create_alias event.

• Creating and updating groups using $groupidentify events and $group properties.

• Calculating bounce rate for web analytics relies on the $pageleave event.

• Calculating exposure and statistical significance for experimentation with the $feature/experiment-feature-flag-key property and $feature_flag_called event.

• Sending data to webhooks is triggered by ingesting specific events.

Anonymous vs identified events

PostHog captures two types of events: anonymous and identified. Identified events enable you to attribute events to person profiles, while anonymous events do not.

See our docs on anonymous vs identified events for more information.

Event properties

Like persons and sessions, events have properties. These are used for filtering, breakdowns, cohorts, targeting, and more.

While ingesting events, PostHog detects some type information for properties such as:

• Strings AKA text (default)
• Boolean
• Dates and timestamps
• Numbers
• Arrays
• Objects

If something has been detected incorrectly, you can manually change the type by going to properties tab in data management, selecting the property, clicking on Edit, and then changing the property type manually. You can also add tags or mark a property as verified on this page.

Default properties

Below is a list of some of the properties that PostHog captures by default in client-side apps. You can see the full list of properties that PostHog captures by default in GitHub.