Events

Last updated:

|Edit this page

What is an event?

An event is any recordable interaction a user has in your application or website. Clicking a button, or visiting a page, is an event. Moving a mouse cursor isn't.

You can create custom events, but PostHog also autocaptures many basic events (e.g. pageviews) for you. See our autocapture docs for more on what it does and doesn't capture.

You can view recent events from the Activity page in PostHog, which can be set to automatically update every 30 seconds for a live view of activity in your app.

Default events and properties

You may notice that some events or properties are prefixed with $ and show a PostHog icon next to them – e.g., $pageview, $feature_flag_called, $current_url, or $os_version. This indicates that these are default PostHog events or properties.

Pageview events

$pageview events are automatically sent when using the JavaScript snippet or SDK. You can disable this by setting capture_pageview: false in the initialization config.

You can manually send pageview events by calling posthog.capture('$pageview'). This is necessary for single-page applications like React, Next.js or Vue, since otherwise a pageview event is only sent for the first page.

Pageleave events

Similar to pageview, $pageleave events are automatically sent. You can disable them by setting capture_pageleave: false in the config. For single-page applications, you'll also need to manually send these events using posthog.capture('$pageleave').

Event filtering

You can filter events by properties and cohorts to focus on specific events that are occurring in your project.

While ingesting events, PostHog detects some type information for properties to allow more intelligent filtering, such as:

  • Boolean
  • Dates and Timestamps
  • Numbers
  • Strings
  • Everything else

If you feel something has been detected incorrectly, you can manually change the type by going to Data management -> Properties selecting an event, clicking on Edit, and then changing the property type manually.

Boolean (true or false)

PostHog detects boolean values and allows filtering by only:

  • equals
  • doesn't equal
  • is set
  • is not set

Dates and Timestamps

PostHog detects several formats of string as dates and times:

In detection, day and month are interchangeable so MM-DD-YYYY would be detected as a date.

Ten and Thirteen digit numbers are detected as timestamps if the property name includes "time" or "timestamp"

Filtering against that property will then show a date picker and allows filtering only:

  • equals
  • before
  • after
  • is set
  • is not set

See also: How PostHog calculates timestamps.

Numeric

PostHog detects numeric properties and allow filtering by only:

  • equals
  • doesn't equal
  • matches regex
  • doesn't match regex
  • greater than
  • lower than
  • is set
  • is not set

Strings (text)

PostHog detects text content. If it is not true/false, numeric, or a date time. You can filter by:

  • equals
  • doesn't equal
  • contains
  • doesn't contain
  • matches regex
  • doesn't match regex
  • is set
  • is not set

Push-based event tracking

Most users of PostHog will want to combine their back-end data, such as user information, with the front end actions of those users in their UI. There are three ways of passing data to PostHog:

Further reading

Want more? Check our full list of PostHog tutorials.

Questions?

  • Lucas
    2 months ago

    Improve Documentation Regarding Complex Event Property Types

    We encountered some confusion when using objects and arrays of objects as properties for custom events. We found that these were being stored as the string [object object] when viewed in the properties dashboard.

    After consulting with Max AI, the recommended solution is to JSON.stringify() these properties before sending the event.

    To improve the developer experience and prevent others from encountering the same issue, could the documentation be updated to clearly outline how object and array property types should be handled, perhaps by explicitly stating the need for stringification or providing this as a recommended practice?

  • Arindam
    3 months ago

    How do posthog categorise events as active and stale?

    How does posthog categorise an event as active and stale? Like after how many days of inactivity of that event is it categorised as Stale. Also in what field is this stored as stale? Have checked all the event properties but it is seen nowhere. But when the stale event is searched in Activities and then events, we can see stale written there

  • Robbie
    3 months ago

    Why uuidv7?

    It's not clear to me why a user's distinct ID should be a uuidv7, over, say, a unique email address. In many apps, users are uniquely identified by their email. While I understand I can attach this as a property, is there really an important distinction between types of distinct identifiers when capturing server-side events?

    • Roni
      3 months ago

      Please note the documentation says "commonly". When you submit events you should be able to use any string as the distinct id. UUIDv7 is used if event is generated by for example posthog-js for an anonymous visitor.

    • Kye
      2 months ago

      A user can often change their email address, and IDs should ideally never change, or change as infrequently as possible.

  • Jorien
    5 months 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
    6 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
    8 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
      6 months 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
      Author6 months ago

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

  • Ahmed
    8 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
    9 months ago

    Browser "Back" or "Forward" events

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

  • Viktor
    9 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
    9 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
    a year 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
      a year 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
    a year 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
      a year 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
    a year 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
    a year 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
      a year agoSolution

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

  • Darshit
    a year 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)
      a year 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
    2 years 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
      Author2 years ago

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

  • Philipp
    2 years ago

    Historic Pageviews

    Hey,

    is it possible to manually send historic pageview events?

    Best Philipp

    • Marcus
      2 years agoSolution

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

  • abhi
    2 years 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
      2 years 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
    2 years ago

    Notifications on events

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

    • Marcus
      2 years 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
      2 years agoSolution

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

Was this page useful?

Next article

Ingestion warnings

Sometimes PostHog runs into problems during ingestion due to incorrect or suboptimal usage of PostHog. For example, if you capture an event with a generic ID like null , PostHog doesn't ingest it. If this happens, we do our best to still ingest the event and we log an ingestion warning. Note: These warnings are sampled. The actual number of events affected may exceed the total displayed. List of ingestion warnings: Refused to merge with an illegal distinct ID Refused to merge an already…

Read next article