<!-- BusyBot node reference — https://busybot.net/tools/posthog/ -->

> Node: PostHog (`posthog`) · Action · v1
> Category: Analytics · Credentials: PostHog API (`postHogApi`)
> Updated: 2026-08-16

# PostHog

> Send analytics data to PostHog: events, identities, aliases, page/screen tracking.

## Overview

PostHog is an open-source product analytics platform. This tool sends data to the PostHog Capture and Batch APIs. It supports four resources: Alias (create aliases to link user IDs), Event (create custom analytics events), Identity (identify users with custom properties), and Track (track page views and screen views). The API key is sent in the JSON request body. Supports both PostHog Cloud (https://app.posthog.com) and self-hosted instances. Events are batched into a single /capture request; all other resources send individual payloads to /batch.

**Category:** Analytics  
**Tool Name:** `posthog`  
**Version:** 1

**Appearance:** Icon: `si-posthog` | Color: `#1D4AFF`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool requires **PostHog API** credentials.
See the [Credentials Guide](https://busybot.net/credentials/post-hog-api/) for setup instructions.

### Resources

| Resource | Value |
|----------|-------|
| Alias | `alias` |
| Event | `event` |
| Identity | `identity` |
| Track | `track` |

### Operations

Each resource has its own Operation list, and three resources share the same operation value (`create`). Pick the resource first, then the operation.

| Resource | Operation | Value | Description |
|----------|-----------|-------|-------------|
| Alias | Create | `create` | Create an alias |
| Event | Create | `create` | Create an event |
| Identity | Create | `create` | Create an identity |
| Track | Page | `page` | Track a page view |
| Track | Screen | `screen` | Track a screen view |

### Parameters

All fields accept expressions, so you can drive them from the incoming item — `{{ $json.userId }}` in Distinct ID, for example.

The input item can also supply values directly: if an incoming item's JSON already carries a `distinctId`, `alias`, `eventName`, `name` or `additionalFields` property, that value is used and the corresponding node parameter is ignored for that item. Rename those fields upstream if you want the node's own settings to win.

#### Alias: Create

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Alias | `string` | Yes | — | The name of the alias to create. |
| Distinct ID | `string` | Yes | — | The user's distinct ID. |
| Additional Fields | `collection` | No | `{}` | Optional context and timestamp for the alias event. |
| — Context (`contextUi`) | `fixedCollection` | No | `{}` | Context properties sent with the event. Add as many key/value pairs as you need. |
| — — Key | `string` | No | — | Name of the context property. |
| — — Value | `string` | No | — | Value of the context property. |
| — Timestamp | `string` | No | — | If not set, it will automatically be set to the current time. Use ISO 8601 format. |

#### Event: Create

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Event | `string` | Yes | — | The name of the event (e.g., "purchase", "signup"). |
| Distinct ID | `string` | Yes | — | The user's distinct ID. |
| Additional Fields | `collection` | No | `{}` | Optional event properties and timestamp. |
| — Properties (`propertiesUi`) | `fixedCollection` | No | `{}` | Event properties. Add as many key/value pairs as you need. |
| — — Key | `string` | No | — | Name of the event property. |
| — — Value | `string` | No | — | Value of the event property. |
| — Timestamp | `string` | No | — | If not set, it will automatically be set to the current time. Use ISO 8601 format. |

#### Identity: Create

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Distinct ID | `string` | Yes | — | The identity's distinct ID. |
| Additional Fields | `collection` | No | `{}` | Optional person properties, message ID and timestamp. |
| — Properties (`propertiesUi`) | `fixedCollection` | No | `{}` | Person properties to set on the identity. Add as many key/value pairs as you need. |
| — — Key | `string` | No | — | Name of the person property. |
| — — Value | `string` | No | — | Value of the person property. |
| — Message ID | `string` | No | — | Optional message identifier. |
| — Timestamp | `string` | No | — | If not set, it will automatically be set to the current time. Use ISO 8601 format. |

#### Track: Page

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Name | `string` | Yes | — | The name of the page or screen. |
| Distinct ID | `string` | Yes | — | The user's distinct ID. |
| Additional Fields | `collection` | No | `{}` | Optional category, context, message ID, properties and timestamp. |
| — Category | `string` | No | — | Category for the page or screen. |
| — Context (`contextUi`) | `fixedCollection` | No | `{}` | Context properties sent with the event. Add as many key/value pairs as you need. |
| — — Key | `string` | No | — | Name of the context property. |
| — — Value | `string` | No | — | Value of the context property. |
| — Message ID | `string` | No | — | Optional message identifier. |
| — Properties (`propertiesUi`) | `fixedCollection` | No | `{}` | Event properties. Add as many key/value pairs as you need. |
| — — Key | `string` | No | — | Name of the event property. |
| — — Value | `string` | No | — | Value of the event property. |
| — Timestamp | `string` | No | — | If not set, it will automatically be set to the current time. Use ISO 8601 format. |

#### Track: Screen

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Name | `string` | Yes | — | The name of the page or screen. |
| Distinct ID | `string` | Yes | — | The user's distinct ID. |
| Additional Fields | `collection` | No | `{}` | Optional category, context, message ID, properties and timestamp. |
| — Category | `string` | No | — | Category for the page or screen. |
| — Context (`contextUi`) | `fixedCollection` | No | `{}` | Context properties sent with the event. Add as many key/value pairs as you need. |
| — — Key | `string` | No | — | Name of the context property. |
| — — Value | `string` | No | — | Value of the context property. |
| — Message ID | `string` | No | — | Optional message identifier. |
| — Properties (`propertiesUi`) | `fixedCollection` | No | `{}` | Event properties. Add as many key/value pairs as you need. |
| — — Key | `string` | No | — | Name of the event property. |
| — — Value | `string` | No | — | Value of the event property. |
| — Timestamp | `string` | No | — | If not set, it will automatically be set to the current time. Use ISO 8601 format. |

#### All Operations

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

Every operation produces **one output item per input item**, and no operation fans out. The PostHog response is **merged onto the input item's JSON** at the top level, so the item keeps the fields it arrived with and gains the response fields; a response field with the same name as an existing item field overwrites it. Binary data on the input item is forwarded.

These are ingestion endpoints, so the response is an acknowledgement rather than a record — typically:

```json
{
  "status": 1
}
```

Use the merged item to carry your own upstream fields forward (`{{ $json.userId }}` still resolves after the node), not to read anything back from PostHog. Nothing about the created event, identity or alias is returned.

**Event: Create** collects the events from every input item and sends them as a single batched request. Each input item still gets its own output item, and they all carry the same batch acknowledgement. If that one request fails, every item in the batch fails together.

The Alias, Identity and Track operations send one request per item and succeed or fail independently.

## Usage Examples

- Create a custom event in PostHog for a user action
- Identify a user with custom properties like name and email
- Create an alias to link two distinct user IDs
- Track a page view for a user
- Track a screen view for a mobile app user

## Example Configuration

Link a second identifier to an existing user:

```json
{
  "type": "posthog",
  "parameters": {
    "resource": "alias",
    "operation": "create",
    "alias": "user-alias-123",
    "distinctId": "user-456",
    "additionalFields": {
      "contextUi": {
        "contextValues": [
          { "key": "device", "value": "mobile" }
        ]
      },
      "timestamp": "2026-01-15T10:30:00Z"
    }
  }
}
```

Record a purchase event with its own properties:

```json
{
  "type": "posthog",
  "parameters": {
    "resource": "event",
    "operation": "create",
    "eventName": "product_purchased",
    "distinctId": "user-789",
    "additionalFields": {
      "propertiesUi": {
        "propertyValues": [
          { "key": "product_id", "value": "prod-123" },
          { "key": "price", "value": "29.99" }
        ]
      },
      "timestamp": "2026-01-15T14:25:00Z"
    }
  }
}
```

Track a click driven entirely by upstream data:

```json
{
  "type": "posthog",
  "parameters": {
    "resource": "event",
    "operation": "create",
    "eventName": "button_clicked",
    "distinctId": "{{ $json.userId }}",
    "additionalFields": {
      "propertiesUi": {
        "propertyValues": [
          { "key": "button_name", "value": "{{ $json.buttonName }}" }
        ]
      }
    }
  }
}
```

Set person properties on a user:

```json
{
  "type": "posthog",
  "parameters": {
    "resource": "identity",
    "operation": "create",
    "distinctId": "{{ $json.userId }}",
    "additionalFields": {
      "propertiesUi": {
        "propertyValues": [
          { "key": "email", "value": "{{ $json.email }}" },
          { "key": "plan", "value": "{{ $json.subscriptionPlan }}" }
        ]
      },
      "messageId": "identity-msg-789"
    }
  }
}
```

Track a web page view:

```json
{
  "type": "posthog",
  "parameters": {
    "resource": "track",
    "operation": "page",
    "name": "{{ $json.pageName }}",
    "distinctId": "{{ $json.userId }}",
    "additionalFields": {
      "category": "Navigation",
      "contextUi": {
        "contextValues": [
          { "key": "referrer", "value": "{{ $json.referrer }}" }
        ]
      },
      "propertiesUi": {
        "propertyValues": [
          { "key": "path", "value": "{{ $json.path }}" },
          { "key": "title", "value": "{{ $json.title }}" }
        ]
      }
    }
  }
}
```

Track a mobile screen view:

```json
{
  "type": "posthog",
  "parameters": {
    "resource": "track",
    "operation": "screen",
    "name": "Settings Screen",
    "distinctId": "mobile-user-303",
    "additionalFields": {
      "category": "App Navigation",
      "contextUi": {
        "contextValues": [
          { "key": "app_version", "value": "2.1.0" }
        ]
      },
      "messageId": "screen-msg-789",
      "propertiesUi": {
        "propertyValues": [
          { "key": "screen_class", "value": "SettingsViewController" }
        ]
      },
      "timestamp": "2026-01-15T16:20:00Z"
    }
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Send analytics events, user identities, aliases, and page/screen tracking data to PostHog.