PostHog Getting Started: Account, Keys, First Request (2026)

Getting started overview

Integrating PostHog for product analytics, feature flags, or A/B testing involves a sequence of steps designed to get data flowing from your application to your PostHog instance. This process generally includes account setup, credential retrieval, and an initial data ingestion request. PostHog offers both a cloud-hosted service and options for self-hosting PostHog, providing flexibility in data control and deployment. The platform supports a wide range of SDKs for various programming languages and frameworks, simplifying integration into existing codebases.

The core components for a successful PostHog integration are the Project API Key and the Instance Host. These credentials authenticate your application with your PostHog project, ensuring that data is securely sent to the correct destination. After setting up your account and obtaining these keys, the next step is to make a first request, typically an event capture, to verify the integration. This guide focuses on getting these foundational elements in place.

Quick Reference: PostHog Getting Started

Create an account and get keys

To begin using PostHog, you first need to establish an account or deploy an instance. PostHog offers two primary deployment models: PostHog Cloud and self-hosting. Each approach has distinct steps for setup and credential retrieval.

PostHog Cloud Setup

1. Sign Up: Navigate to the PostHog signup page. You can register using an email address, Google, or GitHub. The free tier allows for up to 1 million events per month and 5,000 session replays per month, making it suitable for initial exploration and small projects.
2. Project Creation: After signing up, you will be guided through creating your first project. During this process, PostHog will automatically generate the necessary credentials for your project.
3. Retrieve Credentials: Once your project is created, access your project settings within the PostHog UI. Look for the 'Project API Key' and 'Instance Host' (sometimes referred to as 'PostHog Host'). These are crucial for initializing any PostHog SDK or making direct API calls. The Project API Key is a unique identifier for your project, while the Instance Host specifies the endpoint where your data will be sent. Keep these credentials secure, as they grant access to your PostHog project.

Self-Hosted Setup

For developers requiring greater control over their data and infrastructure, PostHog provides self-hosting options. This typically involves deploying PostHog on your own servers or cloud infrastructure using Docker, Kubernetes, or other methods.

1. Deployment: Follow the PostHog self-hosting deployment guides for your chosen environment. This process can vary based on your infrastructure but generally involves setting up a database, a Redis instance, and the PostHog application components.
2. Configuration: During or after deployment, you will configure your PostHog instance. This includes setting environment variables and defining network access. Your 'Instance Host' will be the public URL or IP address where your self-hosted PostHog instance is accessible.
3. Retrieve Credentials: After successful deployment and initial setup, log into your self-hosted PostHog instance's UI. Navigate to your project settings to find the 'Project API Key'. This key functions identically to its cloud counterpart, authenticating data sent to your self-hosted instance.

Your first request

After obtaining your Project API Key and Instance Host, the next step is to make a first request to verify your PostHog integration. This typically involves using one of PostHog's SDKs to capture a simple event. This example will demonstrate how to send an event using the JavaScript and Python SDKs, which are among the most commonly used.

Example with JavaScript SDK

First, ensure you have installed the PostHog JavaScript SDK. If you are using npm or yarn:

npm install posthog-js
# or
yarn add posthog-js

Then, initialize the SDK with your credentials and capture an event:

import posthog from 'posthog-js'

posthog.init('YOUR_API_KEY', {
    api_host: 'YOUR_INSTANCE_HOST'
})

// Capture a simple event
posthog.capture('user_signed_up', {
    plan: 'premium',
    source: 'website'
})

console.log('Event "user_signed_up" sent to PostHog.')

Replace 'YOUR_API_KEY' with your actual Project API Key and 'YOUR_INSTANCE_HOST' with your PostHog instance host (e.g., 'https://app.posthog.com' for cloud, or your custom URL for self-hosted). This code initializes the PostHog client and then captures an event named 'user_signed_up' with associated properties.

Example with Python SDK

Install the PostHog Python SDK using pip:

pip install posthog

Then, initialize the SDK and capture an event:

import posthog

posthog.project_api_key = 'YOUR_API_KEY'
posthog.host = 'YOUR_INSTANCE_HOST'

# Capture a simple event
posthog.capture('distinct_id_of_the_user', 'page_viewed', {'page_name': 'Homepage'})

print('Event "page_viewed" sent to PostHog.')

Similarly, replace 'YOUR_API_KEY' and 'YOUR_INSTANCE_HOST' with your credentials. The Python SDK's capture method requires a distinct_id to identify the user associated with the event, along with the event name and an optional dictionary of properties. For more details on identifying users, refer to the PostHog identify documentation.

After running this code in your application, navigate to the Live Events section or the Data Explorer within your PostHog UI. You should see the captured event appear, confirming that your integration is working correctly.

Common next steps

Once you've successfully sent your first event to PostHog, several common next steps can help you further integrate and utilize the platform's capabilities:

• Identify Users: Implement user identification to associate events with specific users. This is crucial for tracking user journeys, creating cohorts, and personalizing experiences. The posthog.identify() method allows you to link anonymous events to known users and set user properties (e.g., email, name, subscription plan). More information is available in the PostHog user identification guide.
• Track Page Views and Screen Views: For web applications, configure automatic page view tracking. For mobile applications, implement screen view tracking. This provides foundational data for understanding navigation patterns and content engagement.
• Capture Custom Events: Beyond basic events, define and capture custom events that are specific to your application's functionality. These could include button clicks, form submissions, feature usage, or e-commerce actions. Thoughtful event naming and property assignment are key for effective analysis.
• Implement Feature Flags: Use PostHog's feature flags to roll out new features to a subset of users, conduct A/B tests, or enable/disable functionality dynamically without code deployments. Refer to the PostHog feature flag documentation for implementation details.
• Set Up A/B Tests: Design and run A/B tests using PostHog's experimentation tools. This involves defining variations, assigning users to groups, and analyzing the impact of different versions on key metrics. The PostHog experiments guide provides a comprehensive overview.
• Explore Session Replays: If enabled, utilize session replays to visually understand how users interact with your application. This can help identify usability issues and improve user experience. The PostHog session replay documentation explains how to configure and view replays.
• Configure Data Export: For advanced analytics or data warehousing needs, explore options for exporting your PostHog data to external systems. PostHog supports various integrations with data warehouses and other tools.
• Review Privacy Settings: PostHog offers robust privacy controls, including data anonymization and opt-out mechanisms. Review and configure these settings to ensure compliance with relevant regulations like GDPR and HIPAA, as detailed in the PostHog privacy documentation.
• Consult API Reference: For direct integrations or custom requirements not covered by SDKs, consult the PostHog API reference. This provides details on all available endpoints for event ingestion, data querying, and configuration management.

Troubleshooting the first call

Encountering issues during your first PostHog integration is common. Here are some troubleshooting steps and common pitfalls to address if your initial event isn't appearing in PostHog:

1. Check Credentials:
   • API Key: Double-check that the Project API Key you are using matches the one in your PostHog project settings. A common mistake is a typo or using a key from a different project.
   • Instance Host: Ensure the Instance Host (api_host in JavaScript, host in Python) is correctly configured. For PostHog Cloud, this is typically https://app.posthog.com. For self-hosted instances, it should be the public URL of your deployment. Incorrect hosts will result in network errors or events being sent to the wrong place.
2. Network Connectivity:
   • Verify that your application has outbound network access to the PostHog instance host. Firewall rules or network configurations can sometimes block these connections.
   • Check your browser's developer console (for JavaScript SDK) or application logs for any network errors (e.g., 400, 401, 403, 500 status codes) when the event is being sent.
3. SDK Initialization:
   • Confirm that the PostHog SDK is initialized before any capture calls are made. If capture is called before init, events may not be sent.
   • Ensure the SDK is imported correctly and available in the scope where you are making the calls.
4. Event Visibility in PostHog UI:
   • Live Events: After sending an event, check the Live Events stream in your PostHog project. This provides a real-time view of incoming events. If your event appears here, it means data is successfully reaching PostHog.
   • Time Range: When viewing trends or insights, ensure your selected time range includes the period when you sent the test event.
   • Filters: If you have filters applied in your PostHog dashboards, temporarily remove them to ensure your test event isn't being filtered out.
5. Ad Blockers / Browser Extensions:
   • For client-side JavaScript integrations, some browser extensions (e.g., ad blockers, privacy extensions) can block analytics requests. Test in an incognito window or with extensions disabled.
6. Self-Hosted Specifics:
   • If self-hosting, ensure all PostHog services (web, worker, database) are running correctly. Check your server logs for any errors.
   • Verify that the external URL configured for your self-hosted instance is correct and accessible from your application.
7. Consult Documentation:
   • Refer to the PostHog integration documentation for your specific SDK. Each SDK might have unique initialization parameters or common issues.
   • The Mozilla Developer Network HTTP status codes guide can help interpret network errors if they appear in your console or logs.

By systematically checking these points, you can identify and resolve most issues preventing your first PostHog event from being successfully ingested.