[ { "id": "brand-art-requests", "title": "Art, brand, and merch requests", "section": "brand", "sectionLabel": "Brand", "url": "pages/brand-art-requests.html", "canonicalUrl": "https://posthog.com/handbook/brand/art-requests", "sourcePath": "contents/handbook/brand/art-requests.md", "headings": [ "Art board automations", "Hedgehog library" ], "excerpt": "🎨 Need artwork or merch? Please request it using the request templates. Do not request art or merch over Slack or email. All artwork and merch requests are handled by Lottie Coxon, Heidi Berton, and Daniel Hawkins on th", "text": "🎨 Need artwork or merch? Please request it using the request templates. Do not request art or merch over Slack or email. All artwork and merch requests are handled by Lottie Coxon, Heidi Berton, and Daniel Hawkins on the Graphics team. They can help you with things like: Custom visuals for paid ad campaigns Blog and social media artwork New themed hedgehogs Custom CTAs and banners Branded merch Animated UI elements They get a lot of work requests, so they use two separate project boards to organize work – one for merch and one for other art projects. This reflects that merch projects often have much longer timelines and need to be handled differently. Whenever you want to request a new merch design or other artwork, you should use the relevant design request templates in the posthog.com repo – one template for merch, one for other art requests. Each template automatically assigns work to the correct project board. Art board automations The Art & Brand Planning board uses GitHub Actions to keep work moving: Reminders — A daily job (9 AM UTC) posts one time comments on issues that have been stuck in... Feedback/Review for 10+ days: asks if any feedback is needed to move the task forward. No Status for 7+ days: asks someone to pick it up or assign it to a column. Status changes — When an issue’s Status is changed on the board: Moved to \"Done\" → the issue is automatically closed (as completed). Moved to \"Assigned: Daniel\", \"Assigned: Lottie\", or \"Assigned: Heidi\" → other default assignees are removed so only the assigned person is on the issue. Internal requests (from the design team) keep all assignees. These changes do not impact the \"Assigned: Cleo\" column, as Cleo has a different workload. Workflows run under the Art Board Bot GitHub App and live in .github/workflows/ ( art board reminder.yml , art board reminders.yml , art board status change.yml ). To establish a clear connection between the task and the working file, designers will create a frame containing a link to the task. They should then add a link to that frame within the task for easy reference. Lottie and Daniel usually ask for two weeks minimum notice, but can often work faster on things if needed. If your request is genuinely urgent, please share your request issue in team marketing channel and mention Lottie, Daniel, and/or Cory. Hedgehog library For team members we keep all our currently approved hedgehogs in this Figma file. This enables us to look through the library of approved hogs, and to export them at required sizes without relying on the design team. Here's how: 1. Open the Figma file. You can manually browse, or use Cmd + F to search based on keywords such as 'happy', 'sad', or 'will smith'. 2. Select the hog you want. If needed, adjust the size using the 'Frame' menu in the top of the right hand sidebar. 3. At the bottom of the right hand sidebar, select the file type you need in the 'Export' menu, choose @2x , then select 'Export [filename]' to download the image. If you can't find a suitable hog, you can request one from the design team. Non team members can find some of the most used hogs to download on our press page." }, { "id": "brand-designing-posthog-website", "title": "Designing posthog.com", "section": "brand", "sectionLabel": "Brand", "url": "pages/brand-designing-posthog-website.html", "canonicalUrl": "https://posthog.com/handbook/brand/designing-posthog-website", "sourcePath": "contents/handbook/brand/designing-posthog-website.md", "headings": [ "Step 1: Wireframes [Balsamiq]", "Step 2: Hi-fi designs [Figma]" ], "excerpt": "The is responsible for everything you see on posthog.com. We treat our website & docs as a product, which means we're constantly iterating on it and improving it. Because our website has a well defined aesthetic, we ofte", "text": "The is responsible for everything you see on posthog.com. We treat our website & docs as a product, which means we're constantly iterating on it and improving it. Because our website has a well defined aesthetic, we often skip the hifi design process and jump straight from wireframes into code. Having a designer who can code means we can reach the desired level of polish without always having to produce hifi designs, thus leading to huge time savings. Step 1: Wireframes [Balsamiq] We often produce hi fidelity wireframes because this allows us to closely envision a design which in turn helps us skip the hi fi Figma process. Note: Balsamiq uses its own Comic Sans style font. Don't get hung up on this! \"image\" 10%", "Sudden decrease in event volume", "No insights analyzed past week", "Payment failed", "Startup credit will run out this billing cycle", "Organization owner recently removed", "Opportunity indicators", "Forecasted MRR growth", "Organization owner recently added" ], "excerpt": "We use Vitally as a customer success platform. You can log in via Google SSO to view customer data but will need Mine or Simon to grant you admin access to let you manage your accounts. It integrates with our other syste", "text": "We use Vitally as a customer success platform. You can log in via Google SSO to view customer data but will need Mine or Simon to grant you admin access to let you manage your accounts. It integrates with our other systems such as PostHog, Salesforce and Zendesk to give you a complete view of what's going on with your customers. Health scoring Overview Health scores are a great way to assess whether your customer is at risk of churn or in a good state and are a common pattern in Customer Success tracking. We compute an overall health score out of 10 based on the following factors and weighting. You can read more about how Vitally health scores work in their docs here. Health score metrics are divided into two categories: Customer Engagement (25%) and Product Engagement (75%). Customer engagement | Score Name | Measuring | Weighting | | | | | | User engagement | Are they using PostHog regularly? | 15% | | Product experience | Are there negative experiences with the product? | 5% | | Company engagement | Are they engaging with PostHog humans? | 5% | Product engagement | Score Name | Measuring | Weighting | | | | | | Product Analytics | Event volume and users analyzing insights | 33% | | Session replay | Replay volume and users analyzing replays | 20% | | Feature flags & Experiments | Flag requests, users creating feature flags, users creating or viewing experiments | 17% | | Surveys & Data warehouse | Users creating and viewing surveys, volume of rows synced | 5% | Customer engagement Non product metrics, looking holistically at: Are customers using PostHog? Do they have friction when using PostHog? Are they engaging with PostHog humans? User engagement This tracks whether users are logging in to PostHog. It can tell us if customers are getting value from PostHog (regardless of the products they're using). Customers that have a low active user percentage, or only have 1 3 users engaging with PostHog are at risk of churn. | Measure | Poor | Concerning | Healthy | | | | | | | Last seen in product | 5 days | 1 5 days | ≤ 1 day | | Active user percentage | <20% | 20 40% | ≥40% | | Percentage decrease in active user percentage | 20% | 5 20% | ≤5% | | Users engaging with features | <3 | 3 10 | ≥10 | Product experience This looks at the experience of using PostHog. Creating a lot of tickets can mean users are not satisfied with PostHog, haven’t implemented PostHog correctly or aren’t using the product correctly (opportunity to offer training)! Similarly, visiting docs can mean users are trying to do something and could need help. We also look at query failure rate. Failed queries are common (users can cancel a query, there can be SQL syntax errors, etc.), however, a high failure rate means users aren't getting the data they need from PostHog. You should help investigate and provide recommendations. | Measure | Poor | Concerning | Healthy | | | | | | | Tickets created in last 30 days | 10 | 5 10 | ≤5 | | Urgent tickets that remain unresolved | 2 | 0 2 | 0 | | Docs visited in last 7 days | 100 | 20 100 | ≤20 | | Query failure rate in last 7 days | 13% | 5 13% | ≤5% | Company engagement This looks at a customer's engagement with PostHog as a company. Most of PostHog's customers are happily self served so this is weighted very little in the overall healthscore. | Measure | Poor | Concerning | Healthy | | | | | | | Most recent meeting | 90 days | 30 90 days | ≤30 days | | Most recent ticket | 90 days | 30 90 days | ≤30 days | | Total product count | <3 | 3 6 | 6 | Product engagement Across PostHog's products, we look at 2 factors – data volume & user engagement. Data volume This tracks percentage decrease in data volume over the last 30 days. We use success metrics to track billable usage over the last 30 days and compare it with the previous 30 days on a rolling basis. The percentages you see in the tables below are the decrease between the previous and current period. User engagement Data volume is a lagging indicator, by the time it drops, customers may have already decided to churn. We combine data volume with product specific user engagement, measuring the percentage of active users interacting with product features over the last 14 days. There are products we don't include in the health score. Vitally has a limit of max 20 health metrics so we are excluding other products for now as the overall ARR from them are still very low compared to the others. Product analytics | Measure | Poor | Concerning | Healthy | | | | | | | Event count last 30 days (percentage decrease) | 20% | 5 20% | <= 5% | | Active users analyzing insights | <20% | 20 40% | ≥40% | Product analytics usage include: analyzing insights or dashboards, creating or saving insights, creating or updating dashboards Session replay | Measure | Poor | Concerning | Healthy | | | | | | | Replay count last 30 days (percentage decrease) | 20% | 5 20% | <= 5% | | Active users watching replays | <20% | 20 40% | ≥40% | Feature flags & experiments | Measure | Poor | Concerning | Healthy | | | | | | | Decide requests last 30 days (percentage decrease) | 20% | 5 20% | <= 5% | | Active users creating feature flags last 30 days | <5% | 5 20% | ≥20% | | Active users using experiments | <5% | 5 20% | ≥20% | Feature flag usage includes: creating or updating feature flags. We look at this over 30 days instead of the usual 14 as feature flags provide value over a longer time frame. Experiments usage includes: creating experiments, viewing experiments, and launching experiments. Surveys & data warehouse | Measure | Poor | Concerning | Healthy | | | | | | | Active users viewing surveys | <5% | 5 20% | ≥20% | | Rows synced last 30 days (percentage decrease) | 20% | 5 20% | <= 5% | Account indicators Health scores are useful for tracking the long term trends in an account, but occasionally there are more immediate point in time events that we should react to. These are tracked as indicators in Vitally and fall into one of two categories Risk indicators show up red against the account name and indicate potential churn Opportunity indicators show up green against the account name and indicate a potential opportunity for growth Risk indicators These are automatically applied via Vitally playbooks (see the Risk category here): Forecasted MRR decrease Applied if the Forecasted MRR Change is less than 10%, indicating a drop in MRR. We should look into the account to understand whether it is just a reduction in usage, or they are trending towards churn. Increased billing page visits Applied if there have been more than 1 visits to the billing page in the previous 7 days. Can be a good indicator that the customer needs help understanding or reducing their bill. Query failure rate 10% Applied if the Query failure rate over the last 7 days (Success metric) is greater than 10%. Use Vitally to see which user was impacted and see if you can help optimize their queries or flag to our team for investigation. Sudden decrease in event volume Applied if the Event count last 7 days (Success metric) decreases more than 20% versus the previous 7 days. Indicates that they may have turned event tracking off. No insights analyzed past week Applied if insight analyzed was last seen greater than 7 days ago. Indicates that they may have stopped using PostHog to track analytics data. Payment failed Applied if there is a failed payment on their Stripe account. We should reach out to get this resolved ASAP. Startup credit will run out this billing cycle Applied if they are currently in the Startup plan segment but also have Forecasted MRR, meaning that they are on track to make a payment this month. Organization owner recently removed Applied if the Owner role has been removed from a user in the last 14 days. May be a sign that you've lost a champion. Opportunity indicators These are automatically applied via Vitally playbooks (see the Opportunity category here): Forecasted MRR growth Applied if the Forecasted MRR Change is more than 10%, indicating an increase in MRR. We should look into the account to understand whether it is likely to be deliberate or an accidental spike. Organization owner recently added Applied if the Owner role has been added to a user in the last 14 days. This is a good opportunity to reach out to a potential champion if you've not met them before." }, { "id": "cs-and-onboarding-how-we-use-automation", "title": "How we use automation in Customer Success", "section": "cs-and-onboarding", "sectionLabel": "CS and Onboarding", "url": "pages/cs-and-onboarding-how-we-use-automation.html", "canonicalUrl": "https://posthog.com/handbook/cs-and-onboarding/how-we-use-automation", "sourcePath": "contents/handbook/cs-and-onboarding/how-we-use-automation.md", "headings": [ "**How we use automation**", "**Current automation stack**", "**Key automated workflows**", "**Human-first automation philosophy**", "**Working effectively with automations**", "**Requesting new automations**" ], "excerpt": "How we use automation Customer Success at PostHog means managing \\~30 accounts per CSM while maintaining deep, meaningful relationships with each customer. Automation and AI tools can help surface important signals and s", "text": "How we use automation Customer Success at PostHog means managing \\~30 accounts per CSM while maintaining deep, meaningful relationships with each customer. Automation and AI tools can help surface important signals and streamline repetitive tasks, allowing CSMs to focus on strategic guidance and relationship building. Automation should never be used as a replacement for human connection and interaction, but mainly as a tool to help a CSM be better prepared, informed, and effective. Current automation stack PostHog CS leverages several integrated tools to monitor account health and identify opportunities: Core monitoring systems: Vitally : Tracks usage patterns, billing changes, health scores, and engagement metrics. Opportunities and Risks are surfaced via \"Indicators\" Health scores update regularly as a composite of multiple metrics with different weights Data is synced in from Salesforce, PostHog, BuildBetter, and Stripe PostHog pipelines : Alerts for usage milestones, new product adoption, and behavioral changes. These are sent to Vitally, Salesforce, or Slack via PostHog CDP for alerts and data updates. BuildBetter : Analyzes customer calls for feature requests, pain points, and sentiment. Notes from calls are automatically synced to Salesforce and Vitally feature requests and painpoints are automatically added to Vitally and sent to \\ feature request feed channel Zapier : Used for numerous automations such as: Renewal reminders Stale Slack channel notifications Billing updates, failed payments Key automated workflows Account monitoring triggers include: MRR changes exceeding certain thresholds generate investigation tasks inactivity periods to flag engagement reviews New product usage (any amount) creates cross sell opportunity indicator Payment failures and low credit balances to send Slack alerts to assigned CSM Health score changes trigger Vitally indicators Annual renewal dates trigger preparation workflows in advance and a ping in Slack Human first automation philosophy Every automated workflow includes deliberate human decision points. For example, when an account begins using session replay, Vitally creates an indicator suggesting outreach about their use case \\ but the CSM determines whether and how to engage based on the account relationship and context. This approach ensures automation enhances rather than replaces the human elements of customer success. Working effectively with automations Best practices: Review automated tasks such as Vitally indicators, Slack alerts, and customer health scores at least twice weekly. Treat automated insights as starting points for investigation, not final answers\\! Set up individual alerts in Vitally or PostHog CDP that match your own portfolio and experiences As an example, setting up your accounts as a Cohort in PostHog and then setting up CDP alerts/notifications to Slack based on product usage and activity. What remains purely human: Initial customer responses and relationship building Renewal negotiations and strategic planning Technical implementation guidance Complex problem solving and consultative conversations Requesting new automations CSMs are encouraged (as are all PostHog employees) to experiment and surface new ideas frequently in Slack or team stand up. Examples of areas where automations could be useful include, but are not limited to: Time savings versus implementation complexity Impact on customer experience Requirement for human judgment Scalability across the team" }, { "id": "cs-and-onboarding-how-we-work", "title": "How we work", "section": "cs-and-onboarding", "sectionLabel": "CS and Onboarding", "url": "pages/cs-and-onboarding-how-we-work.html", "canonicalUrl": "https://posthog.com/handbook/cs-and-onboarding/how-we-work", "sourcePath": "contents/handbook/cs-and-onboarding/how-we-work.md", "headings": [ "Main metrics for each role", "Book of business", "Customer Success Managers", "Weekly Customer Success standup", "How contractual bonus works - Technical CSMs", "Working with engineering teams", "Working with customers in Slack", "Tools we use" ], "excerpt": "This page covers more of the operational detail of how our team generally works for a broader overview of roles and responsibilities, visit the customer success team page. Main metrics for each role Technical CSM: revenu", "text": "This page covers more of the operational detail of how our team generally works for a broader overview of roles and responsibilities, visit the customer success team page. Main metrics for each role Technical CSM: revenue retention Book of business Customer Success Managers Each CSM is assigned customer accounts accumulating to ~$1.5m ARR to work with. We use the CSM Managed Segment in Vitally to track this against goals and CSMs should not assign this themselves (that's up to Dana or Charles). Weekly Customer Success standup In addition to the weekly sprint planning meeting on a Monday, we do an account review standup on Wednesday to discuss any at risk accounts. The objective of the meeting is to hold each other to account, provide direct feedback, and also support each other. It is a great place to ask for help from the team with thorny problems you should not let your teammates fail. How contractual bonus works Technical CSMs CSMs are responsible for ensuring that a larger book of existing customers both annual and monthly continue to use PostHog successfully. They nurture customers and are product experts this isn't a role of just going back and forth between customers and support engineers, or collecting feedback. This plan will also almost certainly change as we scale up the size and complexity of our success machine! As above, we will always ensure folks are treated fairly when we make changes. Variables Your OTE comprises an 80/20 split between base and contractual bonus. Bonus is paid based on revenue retention above 100%, and is uncapped . For example, if you have 100% revenue retention and your target is 120% revenue retention, you get 0% of bonus. For 120% retention, it's 100% bonus, and for 140% retention, it's 200% bonus. This is on a sliding scale so if you hit 110% retention you get 50% bonus. The Q4 2025 target is 120% half yearly NRR. This may change in future depending on how things go. To calculate retention we use the total usage over the past 2 quarters and annualize this, then compare it to the 2 quarters before that. For monthly customers this is the total of their 6 invoices multiplied by 2 For annual customers, we look at the usage based MRR and multiply by 2 For newer customers: if there's at least 2 quarters of revenue, we use quarter on quarter comparison for that specific customer. If it's a brand new customer with less than 1 quarter of revenue, we start measuring next quarter. Bonuses are paid out quarterly, and in any case after an invoice is paid Bonus payments are made at the end of January, April, July, and October at the end of each quarter, we'll monitor how many invoices actually get paid in the first two weeks of the next quarter. Fraser will send you an email that breaks down how you did. Your bonus is guaranteed at 100% for your first 3 months at PostHog this gives you time to get up to speed, but also if you over perform then you will get your additional bonus. If an account is added to your book: If you inherit a new account that hasn't been managed by a PostHog human before, you have a 3 month grace period if they drop or churn in that initial period, they won't be counted against you. We want to encourage you to right size customers, rather than your deliberately letting them wastefully spend money due to some poor implementation. If you inherit an account from another CSM, AE, or AM, it will count toward your NRR in that quarter, even in the first 3 months. How bonus is calculated: In general, we compare annualized ARR over the past 2 quarters with annualized ARR 2 quarters before. For Q4 2025 bonus: (Q4 + Q3 ARR) vs (Q2 + Q1 ARR) For Q1 2026 bonus: (Q1 + Q4 ARR) vs (Q3 + Q2 ARR) For customers on annual plans, we will look at their usage based spending (instead of total contract amount / 12) If an account is removed from your book mid quarter, they will not be included in bonus calculation. We do this extremely rarely, even if a customer shuts down. If we have to give a customer a big refund, we’ll deal with your bonus on a case by case basis depending on what happened, but usually this will still be counted. Account allocation CSMs manage approximately $1.5M in ARR. This coverage amount will grow ~10% quarterly to match our growth targets. When rebalancing accounts (e.g., if accounts drop below the $20k threshold), we'll bring you up to the current quarter's target amount. Working with engineering teams We hire Technical CSMs. This means you are responsible for dealing with the vast majority of product queries from your customers. However, we still work closely with engineering teams! Product requests from large customers Sometimes an existing or potential customer may ask us to fix an issue or build new features. These can vary hugely in size and complexity. A few things to bear in mind: Engineers at PostHog talk to customers. It's much better to bring engineers onto calls to speak to large customer to talk to them directly than just do the call yourself and copy and paste notes back and forth. This is especially useful if a) the team was already considering building the feature at some point, b) it's an interesting new use case, or c) the customer is really unhappy for valid reasons and could churn. Provide as much internal context as you can. If a customer sends a one liner in Slack, don't just copy and paste into a product team's channel find out as much as you reasonably can first, ask clarifying questions up front etc. Otherwise the relevant team will just ask you to do this anyway. We already have principles for how we build for big customers if you have a big customer with a niche use case that isn't applicable to anyone else, you should assume we won't build for them (don't be mad!) For any feature requests customers care deeply about, we should file and track those in Vitally. Finally, if you are bringing engineers onto a call, brief them first what is the call about, who will be there. And then afterwards, summarize what you talked about. This goes a long way to ensuring sales <\\ engineering happiness. Complicated technical questions You will run into questions that you don't know the answer to from time to time this is ok! Some principles here: Try to solve your own problems. Deep dive the docs, ask PostHog AI, ask the rest of the sales team first a bit of digging is a valuable opportunity for you to learn. Similar to the above, don't just copy and paste questions from Slack with no context. Add some commentary 'they have asked X, their use case is generally Y, I think the answer might be Z is that right?'. Do some of the lifting here, rather than putting all the mental load on an engineering team. Working with customers in Slack Most of our customers use Slack, and it's a great way for us to be responsive to them. Everyone has the permission in Slack to create a Connect channel with a customer, and you should do this as early as possible in your relationship with them. When you've created the channel you should also add Pylon, which is used to sync Slack conversations with Zendesk so that our Support and Engineering teams can work on customer issues in a familiar context. To add Pylon to your customer channel: 1. In the Slack desktop app, click the channel name. 2. On the Settings tab, click Add apps. 3. Type Pylon and click Add. 4. In the popup that appears in the Slack channel, select Customer Channel. 5. Add yourself as the Account Owner. 6. Click Enable. 7. Add Tim, Charles, and Abigail to the channel. Once enabled, you can add the :ticket: emoji to a Slack thread to create a new Ticket in Zendesk. Customers can also do this. Make sure that a Group and Severity are selected or the ticket won't be routed properly. It's your job to ensure your customer issues are resolved, make sure you follow up with Support and Engineering if you feel like the issue isn't getting the right level of attention. Tools we use Gmail We use Gmail for our email and the team uses many different clients from Superhuman to Spark to the default Gmail web interface. Find something that works well for you. To get your own email signature, copy the signature from someone else on the team (like Simon) and then fill in your own details. Calendly: We use Calendly for scheduling meetings. In order to schedule a meeting between a customer and multiple members on the PostHog team, click on \"Event types\" in the left hand navigation, then click \"+ New Event Type\" button in the top right, and select \"Group\" from the dropdown. This will allow you to create a group meeting and add multiple team members to the event and create a link you can share with the customer. BuildBetter: We use BuildBetter for call recording and notetaking. You will need to integrate BuildBetter with your calendar in order for it to automatically join your calls. To do so, click on settings and look for the integrations link under account (not the one under organization) and follow the steps from there. Zoom: We use Zoom for sales calls, and if you have Calendly properly integrated, calls that are booked through the tool will default to Zoom. You can find backgrounds to use for the calls here: This is fine \\(and other awesome PostHog wallpapers\\)." }, { "id": "cs-and-onboarding-lifecycle-csm", "title": "Lifecycle of CSM engagement", "section": "cs-and-onboarding", "sectionLabel": "CS and Onboarding", "url": "pages/cs-and-onboarding-lifecycle-csm.html", "canonicalUrl": "https://posthog.com/handbook/cs-and-onboarding/lifecycle-csm", "sourcePath": "contents/handbook/cs-and-onboarding/lifecycle-csm.md", "headings": [ "Introduction", "Stage 1: Getting started with customers", "Stage 2: Establishing trust", "Stage 3: Getting deeply embedded with customers" ], "excerpt": "This page covers more of the operational details of how our team generally works for a broader overview of roles and responsibilities, visit the customer success team page. Introduction When starting out as a Technical C", "text": "This page covers more of the operational details of how our team generally works for a broader overview of roles and responsibilities, visit the customer success team page. Introduction When starting out as a Technical Customer Success Manager (CSM) at PostHog, you are assigned a book of business with ~30 accounts to work with. It is helpful to think of customer engagement in stages to help us identify how we should connect with customers at each stage. Stage 1: Getting started with customers We've written a lengthy guide on how to get started with customers, so rather than rehash some of that information here, go read that guide instead. Stage 2: Establishing trust Once you've gone through your entire book of business and have completed stage 1, the next stage in our journey is to develop deep trust with our champions. Trust is built over time, based on our interactions and how we manage and nurture those relationships. Some key examples that really help with building trusts with your customers: Show, not tell : Whenever a customer has a support question, or indicates they are trying to accomplish a goal, if possible, help create the solution rather than simply sending them to our docs. It is an opportunity to create an insight or dashboard for the customer, confirm if this is what they wanted, and share with them how you were able to create such an insight or dashboard so they could do it themselves later. Be careful to balance this and not create a dependency situation where customers rely on you to create stuff for them. Be timely on notifications : We have automated alerts set up to flag unusual behavior on an account. This includes things like event spikes or decreases. Sometimes this is unexpected behavior for the customer. Being quick to draw this to their attention can be helpful for the customer to investigate and showcase your helpfulness. If there are other signals, act on it accordingly. If there's public news, such as the company just raised a new funding round, reach out to your champion on this to congratulate them earnestly. Go beyond the basics : In getting started with customers, you focused on getting to know your customers, understanding their business goals, helping with implementation, and optimizing their use. Now is a great time to focus on how you can help them optimize for success. This could be looking at how they're currently engaging with PostHog products, whether there are things they haven't done that might be helpful to implement. For example, have they set up custom tracking funnels for high value metrics, created alerts on customer actions to track, have they tried PostHog AI, or considered implementing other features to augment the data they have (such as error tracking to figure out why conversions drop off). This is a good opportunity to cross sell but also presents an opportunity to help customers understand where they can get more value out of PostHog. Regularly invite new users to the Slack channel : The more people on the customer side who know you exist, the more of them will come to you when they hit PostHog issues. Monthly is a good cadence – Vitally can show you who's new. Establishing trust can take time, and your communication style and actions can play a significant role. It may be worth offering recurring calls with your champion to establish more face to face contact, as this can help you maintain an ongoing pulse on what's happening. Stage 3: Getting deeply embedded with customers At this stage, we're interested in conducting a deep dive and becoming more deeply embedded with their team to work through some of their goals. This could help establish new workflows or setups to gain deeper insights beyond what they've achieved. Here are a couple examples that have came up previously: Building a custom recommendation engine : An ecommerce customer we were working with had implemented PostHog to track key metrics they cared about but wanted to take it a step further and use us as source of truth in customizing visitor experiences to their site. Each returning visitor would see a custom feed just for them based on prior product views, searches, or purchases. This went way beyond the scope of simply tracking events and building dashboards, and there were potential opportunities to work with the customer here on how to custom track events, push data to their backend, and more. Real time alerts : A couple customers had high value actions they wanted to track and get real time notifications on. One customer wanted to track product views, present related purchases for upsell, and get notified when a customer didn't complete a purchase. Another wanted to track downloads and figure out when visitors attempt to access a file but runs into an error. This presented opportunies to understand high value signals for our customer and how we can help them implement a custom solution using PostHog to accomplish their goals. The goal at this stage is to help our customers succeed by getting them the key metrics they care about, and often times, requires us to connect with their team to implement custom code changes at a deeper level to accomplish this. If your champion is in a key decision making position who can get these changes through, that's great, but if not, this is also a great opportunity to ask your champion for an introduction to the key decision maker so you can work close with them to ensure changes can be prioritized. Another method is to reach out to the team lead, such as the head of engineering or head of product, armed with what their quarterly goals are, and offer your assistance directly. You may establish another strong connection this way. Companies have conflicting priorities but by demonstrating you understand what their core goal is, and how PostHog could solve the problem, and finding the key decision maker, you have a higher chance of convincing the team to prioritize the changes now rather than wait to add value." }, { "id": "cs-and-onboarding-new-hire-onboarding-exercise", "title": "New hire onboarding exercise", "section": "cs-and-onboarding", "sectionLabel": "CS and Onboarding", "url": "pages/cs-and-onboarding-new-hire-onboarding-exercise.html", "canonicalUrl": "https://posthog.com/handbook/cs-and-onboarding/new-hire-onboarding-exercise", "sourcePath": "contents/handbook/cs-and-onboarding/new-hire-onboarding-exercise.md", "headings": [ "Tactical questions", "Cohorts", "Activation", "Retention / Usage", "Churn", "Strategic questions", "Example answers" ], "excerpt": "This exercise can help you learn more about your customer’s usage of PostHog while helping you ramp up on your own PostHog skills! Tactical questions To get started you’ll need all the organization IDs for your accounts.", "text": "This exercise can help you learn more about your customer’s usage of PostHog while helping you ramp up on your own PostHog skills! Tactical questions To get started you’ll need all the organization IDs for your accounts. You can get those via SQL query: SELECT DISTINCT posthog org id c, NULL as empty column FROM salesforce.account WHERE owner id = 'your salesforce id' You can find your salesforce ID by going to your profile and copy the text in the website URL after “/User/” then export the results via CSV. (The empty column is there so we have commas as delimiter for the org ids, this allows you to directly copy and paste all the org ids into a filter input text field.) Cohorts 1. Who are all the users in your accounts? 2. Who are all the admins / owners in your accounts? (Hint: check the current organization membership level property) 3. Who are the new users in your account this week? 4. Who are the power users in your account? (Power users can be across multiple products, or you can split it by product. Define a power user as you see fit!) Activation 1. For the new users on your accounts, how many came back to analyze an insight, watch a recording, create a feature flag, etc. within their first week? 2. What are the monthly activation rates across all your accounts for product analytics? (Hint: read this activation metric post and these insights) Retention / Usage 1. Which of your new users have retained their usage after their first 3 months? 2. Which of your organizations have viewed /docs/ pages more than once in the past week? How many /docs/ pages views have there been across accounts for the past week? Churn 1. Have any of your accounts churned from a specific product within the last 3 months? How many/if any across all your organizations within the last 3 months? Strategic questions 1. Are any of your users getting stuck setting up a product? 2. What alerts / CDP destinations can you set up to help you monitor drastic changes in your account metrics in PostHog? 3. What analysis would help understand why accounts take so long to convert from first login to consistent usage? Example answers If you get stuck or want to verify your implementation against an example, below are existing cohorts, insights, etc. to match each question. Cohorts : 1. Example cohort 2. Example cohort 3. Example cohort 4. Example cohort Activation : 1. Example insight Retention / Usage : 1. Example insight 2. Example insight Churn : 1. Example insight Strategic questions : 1. Example funnel Where would you dive deep next from here?" }, { "id": "cs-and-onboarding-new-hire-onboarding", "title": "New starter onboarding", "section": "cs-and-onboarding", "sectionLabel": "CS and Onboarding", "url": "pages/cs-and-onboarding-new-hire-onboarding.html", "canonicalUrl": "https://posthog.com/handbook/cs-and-onboarding/new-hire-onboarding", "sourcePath": "contents/handbook/cs-and-onboarding/new-hire-onboarding.md", "headings": [ "Your first few weeks", "Day 1", "Rest of week 1", "Week 2", "In-person onboarding", "Weeks 3-4", "How do I know if I'm on track?", "PostHog curriculum", "Fundamental", "Product analytics", "Implementation", "Billing", "Intermediate", "Feature flags", "Experiments", "LLM Analytics", "Error Tracking", "Other Products and Features", "Advanced", "Alerting setup (for team leads)" ], "excerpt": "Your first few weeks Welcome to the PostHog Customer Success & Onboarding team! We only hire about 1 in 400 applicants, so you've done well to make it here! Unlike a lot of companies, we don't have a super long onboardin", "text": "Your first few weeks Welcome to the PostHog Customer Success & Onboarding team! We only hire about 1 in 400 applicants, so you've done well to make it here! Unlike a lot of companies, we don't have a super long onboarding process and would prefer you to be up and running with your customer base as quickly as possible. Here are the things you should focus on in your first few weeks at PostHog to help you achieve that. Ramping up is mostly self serve we won't sit you down in a room for training for 2 weeks. If you're not sure who is supposed to make something below happen, the person responsible is almost certainly you! Also look at the sales team's onboarding page for guidance on what not to do when you start. In general, there's a lot of good resources within sales to reference (as we were previously one team!) Day 1 Familiarize yourself with how we work at PostHog. Meet with Dana who will run through this plan and answer any questions you may have. In addition, come equipped to talk about any nuances around how you prefer to work (e.g. schedules, family time etc.). Setup relevant Sales & CS Tools Integrate Gmail with Salesforce and Vitally to enable centralized communication history If you start on a Monday, join your first PostHog All Hands (at 4.30pm UK/8.30am PT) and be prepared to have a strong opinion on whether pineapple belongs on pizza. If you start on a Monday, join your first CS standup. We fill in a GitHub issue every week before this meeting so we are prepared for the discussion topics. Dana will add your GitHub handle to the template. Rest of week 1 Confirm that you have been added as a member to the PostHog organization in GitHub. Fraser can add you if you haven't. Work your way through your GitHub onboarding issue that a member of the created and sent a link to. Ask team members in your region to be invited to some customer calls so you can gain an understanding of how we work with customers. Check out some BuildBetter calls and add yourself to a bunch of Slack channels get immersed in what our customers are saying. There are a few BuildBetter playlists to start with – customer training calls, PostHog knowledge calls, onboarding specialist calls, add to them as you listen! Learn and practise a demo of PostHog. For familiarization and self led training, follow the curriculum. You can work through this with the HogFlix Demo App project which is already populated with data. Alternatively, you can create a new project in EU PostHog instances and hook it up to your own app or HogFlix instance. Read all of the CS section in the Handbook as well as the Sales section, and update it as you learn more. Meet with Charles, the exec responsible for Customer Success. Week 2 During your first week, Dana will figure out your initial book of business (around 30 accounts). We will review these at the start of your second week, and make sure you understand how your targets are set. Shadow more live calls and listen to more BuildBetter recordings. Explore Vitally and Metabase – take note of any questions you have to go through during in person onboarding. Once you have your book of business, try running through the onboarding exercise that Kaya designed to test your skills for working with customer accounts. Towards the end of the week, schedule a demo and feedback session with Dana. We might need to do a couple of iterations over the next few weeks as you take on board feedback, don't worry if that's the case! Get comfortable with the PostHog Docs around our main products. Prioritize your current book of customers, and start reaching out! You should check conversations in Vitally to see if someone else has a prior relationship as they can make a warm intro for you. In person onboarding This typically happens in Week 2 or 3 and runs 3 4 days with a few existing team members, covering: Demo practice session with the team. The data we track on customers in PostHog and some hands on exercises to get you comfortable using PostHog itself. Deep dive on Vitally tracking. No stupid questions session. Weeks 3 4 Focus on taking more and more ownership on calls so that team members are just there as a safety net. Make sure all your tooling and automation are fully set up (health indicators etc.) Continue to meet with your book of customers. How do I know if I'm on track? By the end of month 1: Be starting to solve technical problems for your book with occasional help Be leading customer calls and demos on your own Successfully made contact with everyone in your book of business Update this page and other relevant handbook pages with what you learned during onboarding By the end of month 2: Saved your first 'we're going to churn' it's going to happen, but you're going to save them! Be leading evaluations on your own By the end of month 3: Be independently working with your entire book to solve tricky technical problems with minimal assistant On track to consistently hit your retention targets You've suggested and made changes to our systems that enable you to do your job better Think about customer health scores and add/change anything you learn here PostHog curriculum PostHog has a lot of products! To help you figure out how to start and continue building your knowledge, here's a recommended list of topics to work through. Do not feel as though you need to learn all the products through your first few weeks. Learning is best done working through customer use cases and requests. Add and modify this list as you work through it! Products are added frequently, likely making this list outdated. Fundamental Product analytics 1. Quick primer on Product analytics 2. Creating insights: Trends, Funnels User Paths Wildcard groups Path cleaning Rules Retention, Stickiness, Lifecycle How to filter out test users? 3. Persons What are persons and how are they created? Identify() identified vs anonymous events Pricing 4. Groups – what is it? what is the use case? how is it charged? 5. Session replay – masking, cutting costs, filtering 6. Toolbar – heatmaps, actions Implementation 1. How is PostHog implemented? 2. Autocapture – how do you customize autocapture? How do you leverage autocapture? 3. What are custom events? How do you set custom properties? 4. What is identify? How do you set custom person properties? How do you merge users? What is alias? 5. What are groups? How do you set group properties? 6. What are cohorts? How do you create cohorts (static and dynamic)? How are they different from groups? 7. Projects, organizations and access controls 8. More advanced use cases: Cross domain tracking reverse proxy cookie consent (EU) Billing 1. How to estimate costs 2. Pre paid credits 3. Billing Limits Intermediate Feature flags 1. Creating and using them in code How do I ensure flags are loaded before capturing any events? Can you evaluate feature flags using properties that haven't been ingested yet? 2. Locally testing feature flags using toolbar 3. Insights based on feature flags: Some users have access to a beta feature. How do I filter insights for these users? 4. Local evaluation 5. Client side bootstrapping 6. Troubleshooting Experiments 1. Creating an experiment from PostHog UI 2. Understanding MDE, primary metrics, secondary metrics, interpreting results 3. Traffic allocation configuring it and validating it. What are some reasons why 80/20 split may not be an 80/20 split? 4. Returning users: user sees variant A in session 1, does not convert; user sees variant B in session 2, does convert Does this happen? Can the same user see different variants in different sessions? If so, how does this affect the results? 5. No code web experiments Implementation requirements Landing page experiments – how to deal with flickering of content when page is first loaded? LLM Analytics 1. Implementing with your LLM SDK Privacy options 2. Generations vs traces vs spans vs sessions 3. LLM Cost Analysis How do we accommodate custom LLM pricing? 4. Insight analysis Error Tracking 1. Implementing error tracking 3. Stack traces Uploading source maps Releases 4. Exceptions vs issues What is a fingerprint? Other Products and Features 1. Platform add ons (Boost/Scale/Enterprise/Teams) 2. Data pipelines Sources Destinations Transformations 3. Surveys How surveys works with feature flags/experiments 4. Workflows 5. Logs Advanced 1. SPA (single page apps) 2. API Alerting setup (for team leads) We have certain automations in Vitally that your team lead needs to add you to. Please ask your team lead to add you. Vitally name trait playbook: create a new branch that matches assigned CSM to new team member. In this branch, add action to update account trait CSM name to name of the new team member. This is used to populate account owner info in tickets created by customers we own, so support knows who to reach out to." }, { "id": "cs-and-onboarding-onboarding-success-plan", "title": "Template for onboarding success plan", "section": "cs-and-onboarding", "sectionLabel": "CS and Onboarding", "url": "pages/cs-and-onboarding-onboarding-success-plan.html", "canonicalUrl": "https://posthog.com/handbook/cs-and-onboarding/onboarding-success-plan", "sourcePath": "contents/handbook/cs-and-onboarding/onboarding-success-plan.md", "headings": [ "Introduction", "Customize the below template", "Template", "PostHog 30-Day success plan", "Our shared goal", "Week 1: Quick setup & first insights", "Your commitments", "PostHog commitments", "Week 2-3: Feature Adoption & Optimization", "Together We'll:", "Week 4: Value Confirmation & Next Steps", "Success Review:", "Post-Launch: Optimization Check-in", "6-8 Weeks After Launch:", "Success Metrics", "Key Contacts & Communication", "PostHog Team", "Your Team", "Meeting Schedule", "What You Can Expect From Us", "What We Need From You" ], "excerpt": "Introduction Each customer is going to be a bit unique when it comes to onboarding and implementation; especially with such a broad product surface area! There are still some best practices we can follow to collaborate w", "text": "Introduction Each customer is going to be a bit unique when it comes to onboarding and implementation; especially with such a broad product surface area! There are still some best practices we can follow to collaborate with the customer and plan for their success. It really helps customers to build engagement if we can collaborate with them on a plan for their first 30 days at PostHog. Customize the below template Customize the template with the goals, specific products and commitments that make sense for your customer's use case. Share with customer, ideally as a Slack Canvas Template PostHog 30 Day success plan Customer: [Customer Name] | CSM: CSM or AE NAME | Start Date: [Date] Our shared goal Week 1: You're getting actionable insights from PostHog Week 3: You've identified specific opportunities to improve your key metrics Week 4: You're confident PostHog is driving measurable business value Week 1: Quick setup & first insights Goal: See value within 7 days Your commitments [ ] SDK Validation: Confirm SDK is properly tracking (usually done in trial) [ ] Key Stakeholders: Attend 30 min kickoff call [ ] Custom Events: Define business specific events you want to track [ ] Primary Use Case: Define the 1 metric you want to improve PostHog commitments [ ] Implementation Guidance: Validate SDK setup and custom event tracking [ ] Feature Flags Setup: Configure feature flags for your use cases [ ] Group Analytics Setup: Configure B2B company level tracking [ ] Custom Dashboard: Build initial dashboard for your key metrics [ ] Training Session: 45 min walkthrough of your specific setup [ ] First Insights: Identify 2 3 actionable findings from your data Weekly check in: [Day/Time] 30 minutes What findings have you learned from the first few insights you set up? Have you come across any points of friction in the setup or areas of the product you're struggling to understand? What are the next actions steps for us to follow up with in the next meeting? Week 2 3: Feature Adoption & Optimization Goal: Expand usage across your team Together We'll: Session Replay: Set up recordings for your key user flows Feature Flags: Deploy your first A/B test or feature rollout Surveys: Launch feedback collection (if applicable) Team Training: Onboard 3 5 additional team members Advanced Analytics: Build funnels, cohorts, or retention analysis Bi weekly Check in: [Day/Time] 30 minutes Week 4: Value Confirmation & Next Steps Goal: Quantify business impact and plan expansion Success Review: Measurable Impact: Document specific improvements/insights gained ROI Assessment: Calculate value PostHog has delivered Team Adoption: Confirm regular usage across stakeholders Expansion Opportunities: Identify additional products or use cases Business Review: [Day/Time] 45 minutes Post Launch: Optimization Check in Goal: Maximize ROI and identify expansion opportunities 6 8 Weeks After Launch: Usage Analysis: Review which features are driving the most value Advanced Features: Explore underutilized capabilities Workflow Optimization: Streamline your team's PostHog processes Expansion Planning: Identify additional use cases or team members Success Story: Document wins for internal stakeholders Optimization Review: [Day/Time] 60 minutes Success Metrics | Milestone | Target Date | Success Criteria | Status | | | | | | | SDK Validated | Day 2 | Data flowing correctly into PostHog | ⏳ | | Custom Events Defined | Day 3 | Business specific tracking configured | ⏳ | | Feature Flags & Groups Setup | Day 5 | B2B tracking and flags operational | ⏳ | | Team Trained | Day 7 | 3+ people actively using | ⏳ | | Actionable Insights | Day 10 | 2+ specific findings identified | ⏳ | | Feature Expansion | Day 20 | 2+ products actively used | ⏳ | | Business Impact | Day 28 | Measurable metric improvement | ⏳ | Key Contacts & Communication PostHog Team PostHog Human: [your email] Support Channel: [Dedicated Slack channel/email] Documentation: posthog.com/docs Your Team Executive Sponsor: [Name, Role] Strategic oversight, success validation Technical Lead: [Name, Role] Implementation, data setup Primary Users: [Names, Roles] Daily usage, feedback Meeting Schedule Onboarding Phase: Training sessions and weekly progress check ins Post Onboarding: Monthly or bi weekly check ins recurring What You Can Expect From Us ✅ Rapid Response: Same day replies to questions/issues from your PostHog Human ✅ Proactive Guidance: We'll suggest optimizations based on your usage ✅ Custom Resources: Tailored documentation and best practices ✅ Issue Resolution: PostHog human will resolve issues directly and escalate internally as needed ✅ Product Feedback: Feedback calls or user interviews with product managers or engineers What We Need From You ✅ Clear Objectives: Tell us the specific metrics you want to improve ✅ Custom Event Planning: Help us understand your business specific tracking needs ✅ Stakeholder Engagement: Keep key people involved and responsive ✅ Honest Feedback: Let us know what's working and what isn't ✅ Success Definition: Help us understand what ROI looks like for you Questions or concerns? Reach out anytime our success is measured by your success. This plan is our shared roadmap. We'll adjust it based on your specific needs and progress along the way." }, { "id": "cs-and-onboarding-renewals", "title": "Renewals", "section": "cs-and-onboarding", "sectionLabel": "CS and Onboarding", "url": "pages/cs-and-onboarding-renewals.html", "canonicalUrl": "https://posthog.com/handbook/cs-and-onboarding/renewals", "sourcePath": "contents/handbook/cs-and-onboarding/renewals.md", "headings": [ "Renewal principals", "When to start", "Unique Renewal Cases", "Customers who are projected to run out of credit before renewal", "Customers who are projected to have expiring credits at the end of their contract", "Customers with irregular contracts", "Renewal discussions" ], "excerpt": "Renewal principals Being on a prepaid credit plan usually annual is a win win solution for both PostHog and the customer. Customers get discounts on the credits they purchase and PostHog gets confirmed revenue. When esti", "text": "Renewal principals Being on a prepaid credit plan usually annual is a win win solution for both PostHog and the customer. Customers get discounts on the credits they purchase and PostHog gets confirmed revenue. When estimating renewal amount, we want to make sure we accurately determine the amount of credits the customer will need in the next 12 months (or equivalent period, e.g. if they prepaid for 6 months). This is not an opportunity to upsell do that later by encouraging product usage. This page walks through recommendations for approaching and handling renewals. Contract rules and how to create contracts are covered in relevant pages under our shared processes. When to start Start renewal conversations at least 2 months before the contract renewal date for customers you are already in frequent contact with. For customers who are quiet, start renewal discussions 3 months out to allow more time for re engagement. Vitally and Slack will keep you on track with automated reminders. When a customer hits the 2 month mark, they'll automatically enter the Upcoming renewal segment, you'll get a task assigned to you in Vitally, and Slack will send a notification. Start by sending a message in the shared Slack channel. Things will change in a year – the person you worked with previously may not be the right person this time. Mention when the customer is set to renew and ask if they have any preferred next steps. As you make progress in the renewal discussions, update the renewal opportunity in Salesforce. Unique Renewal Cases Customers who are projected to run out of credit before renewal You will get notified by credit bot in Slack if a customer is set to run out of credits before their renewal date. This is considered an early renewal and follow the same process. If the customer will likely run out of credits before renewal is done, make sure they have a credit card on their account so any overage bills will be paid. Customers who are projected to have expiring credits at the end of their contract It is sometimes the case a customer will have a balance on their account when their contract term ends. This credit balance will expire, and they will still be moved to monthly payments. We have rules in place for this situation, allowing customers to carry over credits on a flat renewal (or higher). If you notice a customer trending towards this, try and engage with the customer to explain this credit expiry and the options available. Use this call to explore projected growth and other use cases and features. In these cases, renewal discussions should start at 3 months, to give time to explore new features and determine if carrying over the credits is valuable to the customer. Customers with irregular contracts Many customers are on legacy contracts that do not adhere to our contract rules. This could include non Net 30 payment terms, unique discounts, legacy pricing, or monthly/quarterly payments. It should be a priority to migrate customers to standard pricing and discounts. Although conversations may be difficult, we should, whenever reasonable, stick to the pricing in our handbook, and freely share that handbook with the customer to defend our point. Trust your judgement on when these irregular terms may be deal breakers, and worth keeping. Renewal discussions Renewal conversations are best done on a call. There can be a lot of moving parts so talking through it is usually a good idea. Before the call, review your customer's usage and start a quote in Quotehog. If you need to look at data beyond the last 6 months, you can use this PostHog dashboard and edit the variables. Check if your customer is on any legacy pricing tiers – either talk to them about moving to standard pricing, or take it into account when building a quote. This call can be an opportunity to explore your customer's PostHog experience so far and upcoming initiatives that you can build on in the future. It's also a good idea to explain how contracts, credits, and discounts work at PostHog – our pricing philosophy and contract rules are handy pages to bring up. When you walk through the quote, start by looking at their past usage – try to anchor to the main products they're using as there can be a lot of numbers to look at. Explain how you estimated the usage for each product to arrive at the final number. Check in with your customer throughout to sense check you're on the right track. After the call share the public quote link with your customer along with any usage information you shared on the call." }, { "id": "docs-and-wizard-snippets-hogref-schema", "title": "Hogref Schema", "section": "docs-and-wizard", "sectionLabel": "Docs and Wizard", "url": "pages/docs-and-wizard-snippets-hogref-schema.html", "canonicalUrl": "https://posthog.com/handbook/docs-and-wizard/_snippets/hogref-schema", "sourcePath": "contents/handbook/docs-and-wizard/_snippets/hogref-schema.mdx", "headings": [ "Root Object", "Info", "Class", "Function", "Parameter", "TypeReference", "Type", "Property", "Example", "Event", "ThrowsClause", "EnumValue", "GenericParameter", "FunctionOverload", "Enumerations", "Example JSON" ], "excerpt": "The hierarchy of the HogRef JSON schema is as follows: Root Object | Field | Type | Required | Description | | | | | | | id | string | ✓ | Unique identifier for the SDK (e.g., 'posthog js', 'stripe node') | | schemaVersi", "text": "The hierarchy of the HogRef JSON schema is as follows: Root Object | Field | Type | Required | Description | | | | | | | id | string | ✓ | Unique identifier for the SDK (e.g., 'posthog js', 'stripe node') | | schemaVersion | string | | Version of this schema format being used | | info | Info | ✓ | Metadata about the SDK | | classes | Class[] | ✓ | Main classes/modules exposed by the SDK | | types | Type[] | | Type definitions, interfaces, and enums | | categories | string[] | | List of functional categories for organizing methods | Info Metadata about the SDK. | Field | Type | Required | Description | | | | | | | id | string | ✓ | Package/library identifier | | title | string | ✓ | Human readable name of the SDK | | version | string | ✓ | Current version of the SDK | | description | string | | Brief description of what the SDK does | | slugPrefix | string | | URL friendly prefix for documentation links | | specUrl | string (uri) | | URL to the source specification or repository | | docsUrl | string (uri) | | URL to the official documentation | | license | string | | License type (e.g., 'MIT', 'Apache 2.0') | | platforms | string[] | | Supported platforms (e.g., 'browser', 'node', 'react native') | Class Main classes/modules exposed by the SDK. | Field | Type | Required | Description | | | | | | | id | string | ✓ | Unique identifier for the class | | title | string | ✓ | Display name of the class | | description | string | | Overview of what this class provides | | functions | Function[] | ✓ | Methods and functions available on this class | | properties | Property[] | | Instance properties of this class | | staticMethods | Function[] | | Static methods on this class | | events | Event[] | | Events emitted by this class | Function Methods and functions available on a class. | Field | Type | Required | Description | | | | | | | id | string | ✓ | Unique identifier for the function | | title | string | ✓ | Function name as it appears in code | | description | string | | Brief description of what the function does | | details | string \\| null | | Extended explanation, usage notes, or caveats | | category | string | | Functional category (e.g., 'Initialization', 'Capture') | | releaseTag | ReleaseTag | | Stability/visibility status of the function | | showDocs | boolean | | Whether to display in public documentation | | params | Parameter[] | | Function parameters | | returnType | TypeReference | | Return type of the function | | examples | Example[] | | Code examples showing usage | | throws | ThrowsClause[] | | Exceptions/errors that may be thrown | | since | string | | Version when this function was introduced | | deprecated | string \\| boolean | | Deprecation notice or true if deprecated | | seeAlso | string[] | | Related functions or documentation links | | path | string | | Source file path for this function | | async | boolean | | Whether this is an async function | | overloads | FunctionOverload[] | | Alternative function signatures | Parameter Function parameters. | Field | Type | Required | Description | | | | | | | name | string | ✓ | Parameter name | | type | string | ✓ | Type annotation for the parameter | | description | string | | What this parameter is for | | isOptional | boolean | | Whether this parameter is optional | | defaultValue | string | | Default value if not provided | | isRest | boolean | | Whether this is a rest parameter (...args) | TypeReference Reference to a type, used for return types and property types. | Field | Type | Required | Description | | | | | | | id | string | | Reference ID to a type definition | | name | string | ✓ | Display name of the type | Type Type definitions, interfaces, and enums. | Field | Type | Required | Description | | | | | | | id | string | ✓ | Unique identifier for this type | | name | string | ✓ | Type name | | description | string | | What this type represents | | kind | TypeKind | | Kind of type definition | | properties | Property[] | | Properties for object types | | enumValues | EnumValue[] | | Values for enum types | | example | string | | Inline type definition or usage example | | path | string | | Source file path | | extends | string[] | | Types this type extends | | generic | GenericParameter[] | | Generic type parameters | Property Properties on types or classes. | Field | Type | Required | Description | | | | | | | name | string | ✓ | Property name | | type | string | ✓ | Type of the property | | description | string | | What this property represents | | isOptional | boolean | | Whether this property is optional | | isReadonly | boolean | | Whether this property is read only | | defaultValue | string | | Default value | | deprecated | string \\| boolean | | Deprecation notice | Example Code examples demonstrating usage. | Field | Type | Required | Description | | | | | | | id | string | | Unique identifier for the example | | name | string | | Title describing what the example demonstrates | | code | string | ✓ | The example code | | language | string | | Programming language (e.g., 'javascript', 'typescript') | | description | string | | Additional explanation of the example | Event Events emitted by a class. | Field | Type | Required | Description | | | | | | | name | string | ✓ | Event name | | description | string | | When this event is emitted | | payload | string | | Type of data passed to event listeners | ThrowsClause Exceptions/errors that may be thrown by a function. | Field | Type | Required | Description | | | | | | | type | string | | Type of error thrown | | description | string | | When this error is thrown | EnumValue Values for enum types. | Field | Type | Required | Description | | | | | | | name | string | ✓ | Enum member name | | value | string \\| number | ✓ | Enum member value | | description | string | | What this enum value represents | GenericParameter Generic type parameters. | Field | Type | Required | Description | | | | | | | name | string | ✓ | Generic parameter name (e.g., 'T') | | constraint | string | | Type constraint (e.g., 'extends string') | | default | string | | Default type | FunctionOverload Alternative function signatures for overloaded functions. | Field | Type | Required | Description | | | | | | | params | Parameter[] | | Parameters for this overload | | returnType | TypeReference | | Return type for this overload | | description | string | | Description specific to this overload | Enumerations ReleaseTag enum: | Value | Description | | | | | public | Stable, public API | | beta | Beta feature, may change | | alpha | Alpha feature, likely to change | | internal | Internal use only | | deprecated | Deprecated, avoid use | TypeKind enum: | Value | Description | | | | | interface | Interface definition | | type | Type alias | | enum | Enumeration | | class | Class definition | Example JSON" }, { "id": "docs-and-wizard-api-specifications", "title": "API specifications", "section": "docs-and-wizard", "sectionLabel": "Docs and Wizard", "url": "pages/docs-and-wizard-api-specifications.html", "canonicalUrl": "https://posthog.com/handbook/docs-and-wizard/api-specifications", "sourcePath": "contents/handbook/docs-and-wizard/api-specifications.mdx", "headings": [ "Where we publish the API specifications", "How the website ingests the OpenAPI spec", "How to update the OpenAPI spec", "Updating the page title and description", "Updating the endpoint title and description", "Updating the endpoint parameters and responses", "Basic usage", "Django uses serializer to validate request body data, validated request can infer the request and response schemas from the serializer definitions.", "Validating query parameters", "Multiple response status codes", "No response body", "Validation modes", "Which endpoints have validated request and response definitions", "The special case for `Capture`" ], "excerpt": "PostHog's API specifications are (mostly) generated automatically from the OpenAPI spec. We have a tooling to generate the API specification markdown files from the OpenAPI spec. Where we publish the API specifications W", "text": "PostHog's API specifications are (mostly) generated automatically from the OpenAPI spec. We have a tooling to generate the API specification markdown files from the OpenAPI spec. Where we publish the API specifications When ever you run the app locally, the API specification is available at /api/schema/ , and you can view it using Swagger UI. On the website, the API specification is available at /docs/api/ . Some of these pages are hand rolled, and some are generated from the OpenAPI spec. | Page | Type | | | | | Overview | hand rolled | | Capture | hand rolled | | Flags | hand rolled | | Queries | hand rolled | | Actions | generated | | Alerts | generated | | Activity log | generated | | Annotations | generated | | Batch exports | generated | | Cohorts | generated | | Dashboards | generated | | Dashboard templates | generated | | Early access features | generated | | Endpoints | generated | | Environments | generated | | Event definitions | generated | | Events | generated | | Experiments | generated | | Feature flags | generated | | Groups | generated | | Groups types | generated | | Hog functions | generated | | Insights | generated | | Invites | generated | | Members | generated | | Notebooks | generated | | Organizations | generated | | Persons | generated | | Projects | generated | | Property definitions | generated | | Query | generated | | Roles | generated | | Session recordings | generated | | Session recording playlists | generated | | Sessions | generated | | Subscriptions | generated | | Surveys | generated | | Users | generated | | Web Analytics | generated | How the website ingests the OpenAPI spec The website ingests the OpenAPI specification during the Gatsby build process in two stages: 1. During sourceNodes : The OpenAPI spec is fetched and parsed using OpenAPIParser and MenuBuilder from the redoc library. This creates a structured menu of API endpoints that's used for navigation. The menu groups endpoints and handles pagination for groups with more than 20 items. 1. During onPostBuild : The build process fetches the OpenAPI spec from https://app.posthog.com/api/schema/ (or from the POSTHOG OPEN API SPEC URL environment variable if set). The spec is then passed to generateApiSpecMarkdown() , which: Iterates through all paths and HTTP methods in the spec For each endpoint with an operationId , creates a markdown file named after the operation ID Recursively extracts all referenced component schemas for each endpoint Generates markdown files containing the endpoint's OpenAPI JSON in a code block Writes these files to public/docs/open api spec/ The generated markdown files are then available at /docs/open api spec/{operationId}.md and are included in the documentation site's API reference section. How to update the OpenAPI spec Any of the automatically generated pages sources from the OpenAPI spec. To update the content of an automatically generated page, you need to update the OpenAPI spec by making changes to the PostHog/posthog repository. Updating the page title and description These updates happen in the PostHog/posthog.com repository. Page title : Update the titleMap object in src/templates/ApiEndpoint.tsx . For example, to change the \"Actions\" page title, modify the actions entry in the map. Page description : Create or update an overview.mdx file in the corresponding API folder. The file should be located at contents/docs/api/{name}/overview.mdx , where {name} matches the API endpoint name (e.g., events , feature flags ). Example: contents/docs/api/events/overview.mdx contains the description that appears at the top of the Events API page. Updating the endpoint title and description These updates happen in the PostHog/posthog repository. Endpoint title : The title is auto generated from the operationId in the OpenAPI spec using the generateName() function in src/templates/ApiEndpoint.tsx . To customize it, update the operationId or description in the Django viewset in the PostHog repository. You basically need to update the path to update the title. Endpoint description : Create an MDX file named after the endpoint's operationId in the appropriate API folder. The file should be located at contents/docs/api/{name}/{operationId}.mdx . Example: contents/docs/api/feature flags/feature flags list.mdx adds custom content that appears under the \"List all feature flags\" endpoint. The content from this file is rendered above the endpoint's description from the OpenAPI spec. Updating the endpoint parameters and responses The endpoint request body parameters, query parameters, path parameters, response body, response headers, API key scopes, etc. are all defined in the Django serializers and viewsets in the PostHog repository. Generally, there are two types of \"views\" in Django and they require different annotations to generate accurate OpenAPI specs. 1. Model based CRUD views : These are views that are backed by Django models. These CRUD views are backed by models defined in the Django ORM. They map literally to Django model fields, and generally don't need any additional annotations for accurate request and response definitions. 2. Function based views : These are views that are backed by Python functions. These views are not backed by models, and generally annotated with @action decorators. For these views, we need to manually annotate request and response definitions. If an endpoint needs additional annotation, you can use the @validated request decorator to annotate the view. This decorator will use the serializers passed in for both validation and annotation of the request bodies, query parameters, and response bodies, ensuring the OpenAPI spec stays accurate (or we know when they're not). Basic usage The @validated request decorator wraps a view function and provides validation for request and response data: Validating query parameters Use query serializer to validate query parameters: Multiple response status codes Declare multiple possible response status codes: No response body Declare status codes with no response body using None : Validation modes By default, @validated request uses strict validation for requests (raises on invalid data) and non strict for responses (logs warnings in DEBUG mode). You can control this: Which endpoints have validated request and response definitions The @validated request decorator is new and many endpoints have not been annotated yet. The following endpoints have been annotated: tasks task runs feature flags feature value We plan on slowly annotating all endpoints with the @validated request decorator through Q1 2026. The special case for Capture Ingestion is basically an entirely different service and not included in the OpenAPI spec. It also has special limitations like batching, rate limiting, etc that need to be documented separately. It doesn't fit the classic patterns for a RESTful API as well as other endpoints. The ingestion team and docs team will need to work together to update the OpenAPI spec for the Capture endpoint." }, { "id": "docs-and-wizard-changelog", "title": "How to publish changelog", "section": "docs-and-wizard", "sectionLabel": "Docs and Wizard", "url": "pages/docs-and-wizard-changelog.html", "canonicalUrl": "https://posthog.com/handbook/docs-and-wizard/changelog", "sourcePath": "contents/handbook/docs-and-wizard/changelog.mdx", "headings": [ "Changelog content and ownership", "What gets included", "How the publishing process works", "How to publish changelog yourself", "Option 1: The main changelog", "Option 2: The product changelogs", "Option 3: Automated drafting via Slack reaction", "Links and resources" ], "excerpt": "We have one of the coolest changelogs on the internet. It's also one of the busiest. As a company that ships weirdly fast, it's important to share what we're working on with as many people as possible, as often as possib", "text": "We have one of the coolest changelogs on the internet. It's also one of the busiest. As a company that ships weirdly fast, it's important to share what we're working on with as many people as possible, as often as possible. The changelog is a great way to do that. `", "Docs components", "Screenshots and gifs", "Videos", "Multi-language code blocks", "Python example", "Callout boxes", "Steps", "Decision tree", "PostHog AI components", "Have a question? Ask PostHog AI", "Platform logos", "Debugging MDX issues" ], "excerpt": "The website's core technical architecture is built and maintained by the . See their handbook pages on the website and MDX components for more information. Gatsby and MDX features Snippets for content reuse Create snippe", "text": "The website's core technical architecture is built and maintained by the . See their handbook pages on the website and MDX components for more information. Gatsby and MDX features Snippets for content reuse Create snippets in a snippets/ directory for content you want to reuse across multiple pages. When to create a snippet: Content appears in 2+ pages Event schemas or property tables Platform specific code blocks Reusable UI components MDX snippets Create an MDX snippet for static reusable content like tables, callouts, or text blocks. Use the snippet in an MDX page like this: TSX snippets Create a TSX snippet for dynamic content for lightweight components or React hooks. Use the snippet in an MDX page like this: If the TSX snippet contains substantial logic, create a reusable component or hook in /src/components/ or /src/hooks/ instead. Frontmatter All .mdx pages support frontmatter, which Gatsby uses to configure page metadata. Here's a table of available frontmatter fields: | Field | Purpose | Example | | | | | | title | Page title | React installation | | platformLogo | Platform icon key for installation pages | react , python , nodejs | | showStepsToc | Show steps in right sidebar TOC | true | | hideRightSidebar | Hide right sidebar TOC on start here and changelog pages | true | | contentMaxWidthClass | Control and customize the width of main content column | max w 5xl | | tableOfContents | Override the auto generated TOC with custom entries | [{ url: 'section id', value: 'Section Name', depth: 1 }] | Magic