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.

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.

Anonymous vs identified events

By default, PostHog captures identified events. This means all events create a person profile and set person properties.

If you don't need person profiles or properties, you can capture anonymous events. Under our current pricing, anonymous events can be up to 4x cheaper than identified events (due to the cost of processing them).

To capture anonymous events, set the person_profiles JavaScript Web config option to identified_only or capture an event with the $process_person_profile property set to false.

posthog.init(
    '<ph_project_api_key>',
    {
        api_host: 'https://us.i.posthog.com',
        person_profiles: 'identified_only'
    }
)