cotera
Logo

PostHog

Authentication Type: API Key Description: Track user events, page views, and screen interactions for product analytics through PostHog.

Authentication

To authenticate with PostHog, you'll need your project API key and host URL:

  1. Log in to your PostHog instance
  2. Go to Project Settings > Project API Key
  3. Copy your project API key
  4. Determine your host URL:
    • PostHog Cloud: https://app.posthog.com
    • Self-hosted: Your custom PostHog instance URL (e.g., https://posthog.yourcompany.com)

You'll need to provide:

  • apiKey string: Your PostHog project API key
  • host string: Your PostHog host URL

Note: The API key is passed in the request body as the api_key field, not as an authorization header. This is how PostHog's ingestion API is designed.

Events

Capture Event

Send a custom event to PostHog for a specific user. Track button clicks, purchases, form submissions, and any other user action you want to measure.

Operation Type: Mutation (Write)

Parameters:

  • event string (required): The name of the event to capture (e.g., button_clicked, purchase_completed)
  • distinctId string (required): A unique identifier for the user performing the action (e.g., user ID, email)
  • properties object (nullable): Additional properties to attach to the event. Can include any key-value pairs relevant to the action.
  • timestamp string (nullable): ISO 8601 timestamp for when the event occurred. If omitted, PostHog uses the current time.

Returns:

  • status number: HTTP status code indicating success (e.g., 200)

Example Usage:

{
  "event": "purchase_completed",
  "distinctId": "user-123",
  "properties": {
    "product_id": "prod-456",
    "amount": 49.99,
    "currency": "USD",
    "payment_method": "credit_card"
  },
  "timestamp": "2025-06-15T14:30:00Z"
}

Track

Track Page View

Record when a user visits a specific page in your web application. Use this to analyze navigation patterns, popular pages, and user engagement.

Operation Type: Mutation (Write)

Parameters:

  • distinctId string (required): A unique identifier for the user viewing the page
  • name string (required): The name of the page (e.g., Home, Pricing, Dashboard)
  • url string (nullable): The full URL of the page (e.g., https://example.com/pricing)
  • properties object (nullable): Additional properties to attach to the page view event
  • timestamp string (nullable): ISO 8601 timestamp for when the page view occurred. If omitted, PostHog uses the current time.

Returns:

  • status number: HTTP status code indicating success (e.g., 200)

Example Usage:

{
  "distinctId": "user-123",
  "name": "Pricing",
  "url": "https://example.com/pricing",
  "properties": {
    "referrer": "https://example.com/home",
    "campaign": "summer-sale"
  }
}

Track Screen View

Record when a user views a screen in your mobile application. Use this to track mobile app navigation patterns and screen-level engagement.

Operation Type: Mutation (Write)

Parameters:

  • distinctId string (required): A unique identifier for the user viewing the screen
  • name string (required): The name of the screen (e.g., HomeScreen, ProfileSettings, Checkout)
  • properties object (nullable): Additional properties to attach to the screen view event
  • timestamp string (nullable): ISO 8601 timestamp for when the screen view occurred. If omitted, PostHog uses the current time.

Returns:

  • status number: HTTP status code indicating success (e.g., 200)

Example Usage:

{
  "distinctId": "user-456",
  "name": "ProductDetails",
  "properties": {
    "product_id": "prod-789",
    "category": "electronics",
    "app_version": "2.3.1"
  }
}

Identity

Identify User

Set or update user properties in PostHog. Use this to enrich user profiles with information like email, plan tier, company, or any custom attributes you want to track.

Operation Type: Mutation (Write)

Parameters:

  • distinctId string (required): The unique identifier for the user to identify
  • properties object (nullable): Key-value pairs of user properties to set or update (e.g., email, plan, company name)
  • timestamp string (nullable): ISO 8601 timestamp for when the identification occurred. If omitted, PostHog uses the current time.

Returns:

  • status number: HTTP status code indicating success (e.g., 200)

Example Usage:

{
  "distinctId": "user-123",
  "properties": {
    "email": "jane@example.com",
    "name": "Jane Smith",
    "plan": "enterprise",
    "company": "Acme Corp",
    "signup_date": "2025-01-10"
  }
}

Alias

Create Alias

Link two user identifiers together in PostHog. Use this to merge an anonymous session with a known user ID after the user logs in, ensuring a unified view of user activity across sessions.

Operation Type: Mutation (Write)

Parameters:

  • distinctId string (required): The primary user identifier (typically the known user ID)
  • alias string (required): The secondary identifier to link (typically the anonymous or previous ID)
  • timestamp string (nullable): ISO 8601 timestamp for when the alias was created. If omitted, PostHog uses the current time.

Returns:

  • status number: HTTP status code indicating success (e.g., 200)

Example Usage:

{
  "distinctId": "user-123",
  "alias": "anon-session-abc-def-789"
}

Common Use Cases

Product Analytics:

  • Track user actions like button clicks, form submissions, and feature usage with custom events
  • Record page views to understand navigation patterns and content engagement
  • Attach rich properties to events for detailed funnel and retention analysis

User Identification:

  • Enrich user profiles with business data such as email, plan tier, and company name
  • Update user properties as they progress through onboarding or change subscription tiers
  • Build detailed user segments based on identified properties

Multi-Platform Tracking:

  • Track page views for web applications and screen views for mobile apps
  • Use consistent distinct IDs across platforms to unify user activity
  • Attach platform-specific properties to differentiate web vs. mobile behavior

Session Merging:

  • Link anonymous visitor sessions to authenticated user identities after login
  • Create aliases to merge pre-signup activity with post-signup user profiles
  • Maintain a complete view of the user journey from first visit through conversion