# PostHog

> Product analytics platform for capturing events, querying analytics data, and managing user profiles.

Source: https://cotera.co/docs/reference/tools/individual-tools/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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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