cotera
Logo

PostHog

Authentication Type: API Key Description: Product analytics platform for capturing events, querying analytics data, and managing user profiles.

Authentication

To authenticate with PostHog, you'll need your host URL and one or both of these credentials depending on which operations you use:

  1. Log in to your PostHog instance
  2. Host URL: Your PostHog region or instance URL. You can use us or eu as shorthand for PostHog Cloud, or a full URL for self-hosted instances.
  3. Project Token (for write operations): Go to Project Settings > Project API Key and copy the token (starts with phc_)
  4. Personal API Key (for read/query operations): Go to your Account Settings > Personal API Keys and create one (starts with phx_)
  5. Project ID (for read/query operations): Found in your PostHog URL (e.g., https://us.posthog.com/project/12345 → project ID is 12345)

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"
}

Analytics

HogQL Query

Run a HogQL query against PostHog for advanced analytics. HogQL is a SQL-like language that can query events, persons, and other PostHog data.

Operation Type: Query (Read)

Parameters:

  • query string (required): HogQL query string (e.g. SELECT event, count() FROM events GROUP BY event ORDER BY count() DESC)
  • limit number (nullable): Maximum number of rows to return (default 100)

Returns:

  • columns array of strings: Column names returned by the query
  • rows array of arrays: Result rows, each row is an array of values matching columns
  • hasMore boolean: Whether there are more results beyond the limit

Example Usage:

{
  "query": "SELECT event, count() as count FROM events WHERE timestamp > now() - interval 7 day GROUP BY event ORDER BY count DESC",
  "limit": 50
}

Persons

Search Persons

Search for users/persons in PostHog by name, email, or distinct ID. Returns person details and properties.

Operation Type: Query (Read)

Parameters:

  • search string (nullable): Free-text search on person name or email
  • email string (nullable): Filter by exact email address
  • distinctId string (nullable): Filter by distinct ID
  • limit number (nullable): Maximum number of persons to return (default 50)

Returns:

  • count number: Total number of matching persons
  • results array of objects: List of matching persons
    • id string: Person ID
    • uuid string: Person UUID
    • name string (nullable): Person display name
    • distinct_ids array of strings: All distinct IDs associated with this person
    • properties object: Person properties (e.g. email, name, plan)
    • created_at string: When the person was first seen

Example Usage:

{
  "search": "jane@example.com",
  "email": null,
  "distinctId": null,
  "limit": 10
}

Get Person

Get detailed information about a specific person in PostHog by their ID, including all properties and distinct IDs.

Operation Type: Query (Read)

Parameters:

  • personId string (required): The person ID (numeric) or UUID to retrieve

Returns:

  • id string: Person ID
  • uuid string: Person UUID
  • name string (nullable): Person display name
  • distinct_ids array of strings: All distinct IDs associated with this person
  • properties object: Person properties (e.g. email, name, plan)
  • created_at string: When the person was first seen

Example Usage:

{
  "personId": "01234567-89ab-cdef-0123-456789abcdef"
}

Get Person Events

List events for a specific person in PostHog. Optionally filter by event name and date range.

Operation Type: Query (Read)

Parameters:

  • personId string (required): The person ID to retrieve events for
  • event string (nullable): Filter by event name (e.g. $pageview, purchase)
  • after string (nullable): ISO 8601 timestamp — only return events after this time
  • before string (nullable): ISO 8601 timestamp — only return events before this time
  • limit number (nullable): Maximum number of events to return (default 50)

Returns:

  • results array of objects: List of events for this person
    • id string: Event ID
    • event string: Event name
    • distinct_id string: The distinct ID that triggered this event
    • properties object: Event properties
    • timestamp string: When the event occurred

Example Usage:

{
  "personId": "01234567-89ab-cdef-0123-456789abcdef",
  "event": "$pageview",
  "after": "2025-06-01T00:00:00Z",
  "before": null,
  "limit": 25
}

Common Use Cases

Product Analytics:

  • Track user actions like button clicks, form submissions, and feature usage with custom events
  • Run HogQL queries for advanced funnel analysis, retention, and cohort breakdowns
  • Record page views to understand navigation patterns and content engagement

User Research:

  • Search for specific users by email or name to investigate their behavior
  • Get person details including all properties and distinct IDs
  • Retrieve a person's event history to understand their journey through your product

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