Events

Last updated:

|Edit this page

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.

Edit properties

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.

NameKeyExample value
Timestamp$timestamp2024-05-29T17:32:07.202Z
OS$osMac OS X
OS Version$os_version10.15.7
Browser$browserChrome
Browser Version$browser_version125
Device Type$device_typeDesktop
Current URL$current_urlhttps://example.com/page
Host$hostexample.com
Path Name$pathname/page
Screen Height$screen_height1080
Screen Width$screen_width1920
Viewport Height$viewport_height950
Viewport Width$viewport_width1903
Library$libweb
Library Version$lib_version1.31.0
Search Engine$search_enginegoogle
Referrer URL$referrerhttps://google.com
Referring Domain$referring_domainwww.google.com
Active Feature Flags$active_feature_flags['beta_feature']
Event Type$event_typeclick
UTM Source$utm_sourcenewsletter
UTM Medium$utm_mediumemail
UTM Campaign$utm_campaignproduct_launch
UTM Term$utm_termnew+product
UTM Content$utm_contentlogolink
Google Click ID$gclidTeSter-123
Google Ads Source$gad_sourcegoogle_ads
Google Search Ads 360 Click$gclsrcdsa
Google DoubleClick Click ID$dclidtestDclid123
Google Web-to-app Measure$wbraidtestWbraid123
Google App-to-web Measure$gbraidtestGbraid123
Facebook Click ID$fbclidtestFbclid123
Microsoft Click ID$msclkidtestMsclkid123
Twitter Click ID$twclidtestTwclid123
LinkedIn Ad Tracking ID$la_fat_idtestLaFatId123
Mailchimp Campaign ID$mc_cidtestMcCid123
Instagram Share Id$igshidtestIgshid123
TikTok Click ID$ttclidtestTtclid123
Plugins Succeeded$plugins_succeeded['GeoIP (56578)']
Plugins Failed$plugins_failed['plugin3']
Plugins Deferred$plugins_deferred['plugin4']
IP Address$ip192.168.1.1

Questions? Ask Max AI.

It's easier than reading through 573 docs articles.

Community questions

  • Jorien
    3 days ago

    Filter our users to prevent events from being tracked (and billed)

    Is there a way only track part of our users to make the results load faster and maybe even more important decrease the billing costs?

  • Faiq
    2 months ago

    How to get key values from a property of the custom event

    Hi, i need to pick a key value from a property e.g customData that i sent in my custom event. CustomData is an object from which i need to pick some key values that i need to apply filter on. How can i do that? When adding a filter it shows the customEvent in the property dropdown but how do i pick its nested key value?

  • Slavo
    3 months ago

    How set path aliases?

    I need to set up path aliases, so that I can easily filter dashboards or insights by certain pages. Something along like this alias "Dashboard" would map all paths that follow a pattern like "Company/{id}/dashboard".

    It's impractical to always write a regex for this and a big barrier for casual users. How can I achieve something like this? Basically, like actions can be defined via the toolbar, it would be great to also identify "pages" like this.

    • Nicolas
      a month ago

      Did you figure it out how to do this? I would be ok also to have a regex that will populate an extra property in the Pageview event

    • Slavo
      Authora month ago

      Well, not really. I think I even emailed them and found out it's not supported.

  • Ahmed
    4 months ago

    Webhook / Data pipeline

    Here is the grammatically corrected version:

    I need to call the API of my app when there is a change in a feature flag or when someone enables or disables a feature flag. Is there any event available in PostHog for this?

  • Huy
    4 months ago

    Browser "Back" or "Forward" events

    Is it possible to capture events where user clicking on "Back" or "Forward" in the browser?

  • Viktor
    4 months ago

    Stop tracking some of custom events not removing them from the code

    I currently do not need to track some of my custom events, but I don't want to remove them from the code. Is there a way to stop tracking them by adding them to the "blacklist" in the Posthog admin so that they don't waste their quota?

  • Eloïse
    5 months ago

    Types of properties

    Hey! I created a custom event 'copy-response':

    posthog.capture('copy-response', {
    message_id: message.id,
    request_type: message.type_question,
    });

    I have two questions about the type of the properties 'message_id' and 'request_type':

    1- If I explicitly specify their types in the code, does PostHog use that instead of its automatic detection? Does it override what PostHog guesses?

    2- What happens if the values don't match the types PostHog expects? Does it discard the value, set it to null, or raise an error?

    Thanks!

  • Daniel
    7 months ago

    Find usages of an event

    Hi there! Is there a way to find "usages" of an event (e.g. in insights)? Use case e.g.: I want to rename an event for naming consistency and update all insights accordingly. Is there some support for this in PostHog?

    • Marcus
      7 months ago

      Hey Daniel, that is currently not supported, but feel free to subscribe to this feature request. Note that you can create an Action that would match both the old and new event_name to give you a fluent transition in your insights, without losing historical data.

  • Jannes
    7 months ago

    What does the posthog symbol in the event properties overview mean?

    Hello everyone, I'm not sure when this little hedgehog appeared in the event properties overview. I understood that all posthog properties with a "$" in front of them have this little hedgehog. However, this is not the case, as "app version", which I am sending as versions along, is an additional property, and it does not have a "$" in front of it.

    CleanShot 2024-08-09 at 16.16.43.pngCleanShot 2024-08-09 at 16.07.29.png

    • Marcus
      7 months agoSolution

      Hey Jannes, we have a hardcoded list of "Official PostHog properties" in this file and version is one of them. It shouldn't impact any functionality. You'll have to use another property name to avoid having the PostHog icon in front of it.

  • Oskar
    7 months ago

    Event tags in queries

    Hi! If I add tags to my events, can I use them in SQL/ HogQL queries? What would such a query look like? best regards Oskar

  • ravjot
    9 months ago

    unable to add event description

    How do we add event description? either here or via code? Couldn't find anything related to capturing event in code via posthog.capture in docs nor is the there ability to edit/add description in data management image.png

    • Marcus
      9 months agoSolution

      Hey Ravjot, features for collaboration with team members (including event descriptions) are only available when subscribed to the teams addon.

  • Darshit
    9 months ago

    Flutter Web App

    Hello, Post-hog event capture is not working when i make a build, but when i debug its working as expected. Please give me appropriate solution for this issue I am facing while implementing post-hog service for flutter web app.

    • Manoel(he/him)
      9 months ago

      Hello Darshit,

      Can you share the PostHog Flutter SDK code snippets you have in your app so I can take a look? might be a misconfiguration or something.

      Can you call posthog.debug(true) before capturing an event and checking the console logs?

      Thanks.

      Best, Manoel

  • Rafael
    a year ago

    How activity reporting works

    Does the activity report happen only in batches? I noticed that after capturing a single event, it is not updated in the activity tab. It is only updated after I send a few (I send pageviews serverside, I have to refresh a couple of times to start seeing the dump of events). I use lambda and await the flushAsync in every capture.

    • Marcus
      a year ago

      Hey Rafael, note that the activity tab will only refresh once every 30 seconds.

  • Evgeny
    a year ago

    customize default event, like pageView

    In react I need to put screen name as additional property to default PostHog PageView event. Is it possible or I just need to create own custom event?

    • Evgeny
      Authora year ago

      didn't get it properly. used '$pageview' as eventname, works.

  • Philipp
    a year ago

    Historic Pageviews

    Hey,

    is it possible to manually send historic pageview events?

    Best Philipp

    • Marcus
      a year agoSolution

      Hey, checkout this page for instructions on how to import events.

  • abhi
    a year ago

    Question

    In nextjs app . i set autocapture events but i want capture events only for some pages. is it possible to neglect remaining pages specifically pageview and pageleave event ?

    • Marcus
      a year agoSolution

      Hey Abhi, it's not possible to enable autocapture only for some pages. You'll need to enable or disable autocapture for the entire session. But note that you can disable $autocapture events separately from $pageview or $pageleave events.

  • Fredy
    a year ago

    Notifications on events

    How can i get notifications when a certain event occurs, email, sms or webhook

    • Marcus
      a year ago

      Hey Fredy, we do not support sms or email notifications. But if you create an Action, you'll have the option to call a webhook whenever the Action is being triggered.

    • Cory
      a year agoSolution

      This can be done by sending your webhook to Zapier and then doing something with it from there!

  • Julian
    a year ago

    Zapier events, not allowing "Numeric" values

    Hey there! I'm currently sending Event data to Posthog through Zapier, but I'm facing an issue where Posthog is not identifying numeric values as "Numeric" and it keeps defaulting to "string".

    I've tried several number formats (1,000 / 1000 / 1000.00 / etc..)

    None of these are ingested as Numeric values. Is there any way to resolve this?

  • Jesper
    2 years ago

    Arrays in properties

    Hello, we have a " purchase " event where one of the properties is "category," an array containing one or multiple strings. When looking at Live events for purchase, the data is xx separate strings as we want - e.g., Travel, Movie, Documentary. But when creating an insight, it shows the array instead of the strings one by one. E.g. ["Travel","Movie","Documentary"] which makes it challenging to identify the most popular categories.

  • James
    2 years ago

    Delete Events

    Hello,

    How do you delete events? I created a lot of unnecessary ones while integrating Posthog and now I need to remove them.

    Any advice would be greatly apprecaited!

    Thanks, James

    • Paul
      2 years agoSolution

      Hi James!

      Although there's no way to directly delete events, the best option to keep these old events from interfering is to create a new project to handle all your events in the future. I'd recommend keeping the old project around in case you need to do more testing or prototyping, but you could also delete it if you don't have any use. Hope that helps!

    • Fille
      a year ago

      So If I use Posthog for a long time and use lots of events.. makes some misstakes on the way.. there is no way to remove the clutter when setting upp new insights? ..

Was this page useful?

Next article

Anonymous vs identified events

How to capture anonymous events How to capture identified events Mobile SDK version considerations When using PostHog's mobile SDKs, any changes made to personProfiles configuration will only apply to users who have updated their app to the latest version. This is because mobile SDKs are bundled with your app and cannot be updated dynamically. Impact on existing users: Users running older versions of your app will continue using the personProfiles configuration that was bundled with their…

Read next article

PostHog.com doesn't use third party cookies - only a single in-house cookie.

No data is sent to a third party.

Ursula von der Leyen, President of the European Commission