Skip to main content

PostHog

PostHog is an open-source product analytics platform that helps teams understand user behavior through events, feature flags, session recordings, cohorts, and experimentation. It provides a complete toolkit for product analytics, A/B testing, and user insights.

Authentication Types​

PostHog supports Personal API Key authentication:

  • Personal API Key
    • Pros: Simple to set up, supports scoped permissions for enhanced security, no OAuth flow required
    • Cons: Keys must be kept secure and should not be used in frontend code
    • Best for: Server-side integrations, automation scripts, and AI assistants

General Settings​

Before using the connector, you need to configure your Instance URL:

  • Instance URL - The base URL of your PostHog instance
    • US Cloud: https://us.posthog.com
    • EU Cloud: https://eu.posthog.com
    • Self-hosted: Your custom domain (e.g., https://posthog.yourcompany.com)
tip

Choose the correct region for your PostHog account. US and EU Cloud are completely separate instances with no data transfer between them. If you're unsure, check your PostHog URL when logged in - it will show either us.posthog.com or eu.posthog.com.

Setting up Personal API Key​

Follow these steps to create a Personal API Key for PostHog:

  1. Log in to your PostHog account at your instance URL (US Cloud, EU Cloud, or self-hosted)

  2. Click your profile icon in the top right and select Settings from the dropdown

  3. Navigate to Personal API Keys in the left sidebar

  4. Click + Create a personal API key

  5. Configure your API key:

    • Label: Give your key a descriptive name (e.g., "AI Assistant Integration")
    • Scopes: Select the permissions your integration needs. For full AI assistant access, consider enabling:
      • project:read - Read project information
      • feature_flag:read and feature_flag:write - Manage feature flags
      • cohort:read and cohort:write - Manage cohorts (user segments)
      • person:read - Read person/user data
      • dashboard:read and dashboard:write - Access and create dashboards
      • session_recording:read - View session recordings
      • endpoint:read - Execute custom analytics endpoints
      • annotation:read and annotation:write - Manage annotations
      • user:read - Read current user information

  6. Click Create key

  7. Important: Copy the API key immediately - you won't be able to see it again after leaving the page

  8. In your integration settings:

    • Set Instance URL to your PostHog instance URL (e.g., https://us.posthog.com)
    • Paste the Personal API Key into the authentication field
Scope Recommendations

Start with read-only scopes (project:read, feature_flag:read, etc.) and only add write permissions as needed. You can create multiple API keys with different scopes for different use cases. PostHog allows up to 10 personal API keys per account.

Available Tools​

The PostHog connector provides 25 tools organized into the following categories:

Projects & Organizations (3 tools)​

  • List Projects - Discover available projects and get project IDs
  • Get Project - View detailed project settings and configuration
  • Get Current User - Verify authentication and user information

Feature Flags (5 tools)​

  • List Feature Flags - Browse all feature flags with filtering options
  • Get Feature Flag - View detailed flag configuration and rollout rules
  • Create Feature Flag - Create new flags for gradual rollouts or A/B tests
  • Update Feature Flag - Modify flag settings, targeting, or variants
  • Delete Feature Flag - Remove flags that are no longer needed

Cohorts (5 tools)​

  • List Cohorts - View all user segments (cohorts) in the project
  • Get Cohort - See cohort definition and membership count
  • Create Cohort - Define new user segments (static or dynamic)
  • Update Cohort - Modify cohort filters or settings
  • Get Cohort Persons - List users who match cohort criteria

Persons (3 tools)​

  • List Persons - Browse user profiles and properties
  • Get Person - View detailed person information
  • Update Person Property - Modify user properties programmatically

Session Recordings (2 tools)​

  • List Session Recordings - Find session recordings for analysis
  • Get Session Recording - View recording details and playback information

Dashboards (3 tools)​

  • List Dashboards - Browse analytics dashboards
  • Get Dashboard - View dashboard contents and insights
  • Create Dashboard - Create new dashboards for organizing analytics

Query & Analytics (2 tools)​

  • List Custom Endpoints - View optimized analytics endpoints
  • Run Custom Endpoint - Execute custom queries with better performance

Annotations (2 tools)​

  • List Annotations - View markers for important events
  • Create Annotation - Mark releases, incidents, or campaigns on insights

Common Use Cases​

Analyzing Feature Flag Adoption​

1. Use "List Feature Flags" to see all flags in your project
2. Use "Get Feature Flag" to check rollout configuration for specific flags
3. Use "List Cohorts" to see which user segments are targeted
4. Use "Run Custom Endpoint" to query flag evaluation metrics

Creating User Segments for Experiments​

1. Use "List Persons" to understand your user base
2. Use "Create Cohort" to define a user segment based on properties or behavior
3. Use "Get Cohort Persons" to verify the cohort includes the right users
4. Use "Create Feature Flag" to target the cohort with a new feature or experiment

Investigating User Behavior​

1. Use "Get Person" to view a specific user's profile
2. Use "List Session Recordings" to find their recent sessions
3. Use "Get Session Recording" to review session details and playback URLs
4. Use "Update Person Property" to tag the user for follow-up

Monitoring Product Analytics​

1. Use "List Dashboards" to see available analytics dashboards
2. Use "Get Dashboard" to retrieve dashboard data and insights
3. Use "List Annotations" to see what events have been marked
4. Use "Create Annotation" to mark new releases or campaigns

Troubleshooting​

Authentication Errors​

Issue: "Invalid Personal API key" error

Cause: The API key is incorrect, expired, or has been deleted

Solution:

  1. Verify you copied the entire API key without spaces
  2. Check that the key hasn't been deleted in PostHog settings
  3. Generate a new Personal API Key if needed
  4. Ensure you're using the correct Instance URL for your key (US vs EU vs self-hosted)

Wrong Instance URL​

Issue: Connection timeouts or 404 errors

Cause: Instance URL is incorrect or doesn't match your PostHog account

Solution:

  1. Verify your PostHog region by logging into PostHog and checking the URL
  2. US Cloud users should use: https://us.posthog.com
  3. EU Cloud users should use: https://eu.posthog.com
  4. Self-hosted users should use their custom domain without trailing slashes

Insufficient Permissions​

Issue: "Forbidden" or 403 errors when using specific tools

Cause: Personal API Key doesn't have required scopes

Solution:

  1. Go to PostHog Settings → Personal API Keys
  2. Find your API key and click to edit scopes
  3. Enable the required scope(s) for the operation you're trying to perform
  4. Save changes - the key will work immediately with new permissions

Rate Limiting​

Issue: "Rate limit exceeded" errors

Cause: Too many API requests in a short time period

Solution:

  • Analytics endpoints: Limited to 240 requests/minute and 1,200/hour
  • Query endpoint: Limited to 2,400/hour
  • Other CRUD endpoints: Limited to 480/minute and 4,800/hour
  • Consider using Custom Endpoints (via "Run Custom Endpoint") for better rate limits
  • Use pagination and limit parameters to reduce request volume
  • Add delays between requests for batch operations

Project ID vs Project UUID​

Issue: Tools not working with project identifiers

Cause: Some endpoints use numeric project IDs, others use UUIDs

Solution:

  • Most tools in this connector use the numeric project_id
  • Use "List Projects" to find both the ID and UUID for your project
  • The project ID is typically shown in the PostHog URL when navigating to a project
  • If an endpoint requires a different identifier format, the tool description specifies which one

API Documentation​

For more detailed information about PostHog's API, visit:

Regional Data Compliance​

PostHog offers separate US and EU cloud instances to help with data compliance:

  • US Cloud (https://us.posthog.com) - Data stored in the United States
  • EU Cloud (https://eu.posthog.com) - Data stored in AWS EU Central (Frankfurt, Germany), fully GDPR compliant

The instances are completely independent with no data transfer between them. Choose the region that matches your compliance requirements.