PostHog is a product analytics platform for tracking user behavior, product usage, and event-level activity. The Nekt PostHog connector extracts project metadata and event data into your Catalog so you can analyze product engagement at scale.

Configuring PostHog as a Source

In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the PostHog option from the list of connectors. Click Next and you’ll be prompted to add your access.

1. Add account access

The following configurations are available:

Personal API key: Personal API key used to authenticate against the PostHog API. See the official PostHog API docs.
Base URL: API base URL for your PostHog region or self-hosted environment.
- US Cloud: https://us.posthog.com
- EU Cloud: https://eu.posthog.com
- Self-hosted: your own PostHog domain
Start date: Earliest date from which events are synced (e.g., YYYY-MM-DD). This date acts as a strict lower bound for your data: even if you choose a FULL_TABLE sync type, the connector will honor this configured start date as the starting boundary (using it as the after parameter), ensuring you don’t inadvertently pull the entire workspace history.

Event payloads can be large. Choosing a very old start date may significantly increase the first sync duration.

Once you’re done, click Next.

2. Select streams

Choose which data streams you want to sync. For faster extractions, select only the streams relevant to your analysis.

Tip: In addition to the projects stream, the connector creates one dynamic event stream per PostHog project using the pattern {organization_slug}_events_{project_name}.

Select the streams and click Next.

3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table, and the type of sync.

Layer: Choose the layer where extracted PostHog tables will be created.
Folder: Optionally group all PostHog tables inside a folder.
Table name: A default name is suggested, but you can customize it and optionally apply a prefix.
Sync Type: Choose between INCREMENTAL and FULL_TABLE.
- Incremental: Recommended for event streams, using timestamp as the replication key.
- Full table: Suitable for projects metadata refreshes.

Once you are done configuring, click Next.

4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters. To define your Trigger, consider how often your product analytics data should be refreshed. Optionally, you can define:

Delta Log Retention: How long Nekt keeps previous table states. See Resource control.
Additional Full Sync: Periodic full syncs to complement incremental runs.

When you are ready, click Next to finalize the setup.

5. Check your new source

You can view your new source on the Sources page. If needed, manually trigger the extraction by clicking on the arrow button. Once a run completes successfully, your data appears in the Catalog.

You need at least one successful source run to see the tables in your Catalog.

Streams and Fields

Below you’ll find the available PostHog streams and their core fields.

Projects

Project metadata for each organization available to the API token.Key fields:

Field	Type	Description
`id`	Integer	Project identifier (primary key)
`uuid`	String	Project UUID
`organization`	String	Organization identifier linked to the project
`name`	String	Project name
`api_token`	String	Project ingestion token
`timezone`	String	Project default timezone
`is_demo`	Boolean	Indicates whether the project is a demo project
`ingested_event`	Boolean	Indicates whether at least one event has been ingested
`completed_snippet_onboarding`	Boolean	Onboarding status for snippet setup
`has_completed_onboarding_for.feature_flags`	Boolean	Feature flags onboarding status
`access_control`	Boolean	Access-control enablement flag

Notes:

Stream name: projects
Primary key: id
Replication: full-table style (no replication key)

Events (dynamic per project)

Event-level analytics data from each PostHog project. The connector dynamically creates one stream per project discovered during catalog discovery.Dynamic stream naming:

{organization_slug}_events_{project_name} (slugified with underscores)

Key fields:

Field	Type	Description
`id`	String	Event identifier
`distinct_id`	String	User or actor distinct identifier
`event`	String	Event name
`timestamp`	DateTime	Event timestamp (replication key)
`properties`	String	JSON Array of key/value event properties
`person.is_identified`	Boolean	Whether associated person is identified
`person.distinct_ids`	String	JSON Array of associated person distinct IDs
`person.properties.email`	String	Associated person email (when available)
`elements`	String	JSON Array of captured element metadata
`elements_chain`	String	Serialized chain of captured elements for the event

Notes:

Primary keys: id, distinct_id
Replication key: timestamp
Incremental sync uses start_date for the first run, then continues from saved state.

Data Model

The connector follows an organization/project-based model:

Use Cases for Data Analysis

This section includes practical SQL examples you can run in Explorer.

1. Event volume by day

Measure daily event volume to track product activity trends.

SQL query

SELECT
   DATE(CAST(timestamp AS timestamp)) AS event_date,
   event,
   COUNT(*) AS total_events,
   COUNT(DISTINCT distinct_id) AS unique_users
FROM
   nekt_raw.posthog_org_events_project
GROUP BY
   1,
   2
ORDER BY
   event_date DESC,
   total_events DESC;

SELECT
   DATE(TIMESTAMP(timestamp)) AS event_date,
   event,
   COUNT(*) AS total_events,
   COUNT(DISTINCT distinct_id) AS unique_users
FROM
   `nekt_raw.posthog_org_events_project`
GROUP BY
   1,
   2
ORDER BY
   event_date DESC,
   total_events DESC;

2. Top users by event activity (last 30 days)

Identify the most active users based on tracked events.

SQL query

SELECT
   distinct_id,
   COUNT(*) AS event_count,
   MIN(CAST(timestamp AS timestamp)) AS first_event_at,
   MAX(CAST(timestamp AS timestamp)) AS last_event_at
FROM
   nekt_raw.posthog_org_events_project
WHERE
   CAST(timestamp AS timestamp) >= current_timestamp - interval '30' day
GROUP BY
   1
ORDER BY
   event_count DESC
LIMIT 100;

SELECT
   distinct_id,
   COUNT(*) AS event_count,
   MIN(TIMESTAMP(timestamp)) AS first_event_at,
   MAX(TIMESTAMP(timestamp)) AS last_event_at
FROM
   `nekt_raw.posthog_org_events_project`
WHERE
   TIMESTAMP(timestamp) >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
GROUP BY
   1
ORDER BY
   event_count DESC
LIMIT 100;

Implementation Notes

Data Sync Behavior

Reliable Ascending Extraction: The default descending order provided by PostHog’s API can drop events due to windowing behavior. To prevent this, the connector explicitly requests events in strict ascending order based on timestamp, ensuring a gap-less, reliable data extraction.
Dynamic Time-Sliced Pagination: The events endpoint is paginated using bounded time slices to keep queries efficient and strictly prevent timeouts or reaching API limits. A slice starts at 1 day and can adaptively grow up to 32 days if read in one page, or shrink if yielding a large number of events. Furthermore, page size is capped at 1,000 events.
Ingestion Delay Margin: To ensure events still being ingested by PostHog are not skipped, the connector stops reading exactly 10 minutes before the current stream start time. This buffer avoids situations where an event arrives slightly late and is permanently left behind the saved replication bookmark.
Full Table Syncs and Start Date: The connector explicitly enforces the configured Start date even during FULL_TABLE syncs. When starting a full refresh where no prior extraction state is present, the API request falls back to the configured start date as the absolute lower boundary. This prevents the connector from inadvertently pulling the entire history of your PostHog workspace.
Memory Batch Size Limit: Since PostHog events are exceptionally wide (spanning hundreds of properties and utilizing ~50–80 KB per record), Nekt caps the batch size in memory per stream to keep memory usage bounded and stable during extractions.

Skills for agents

Download PostHog skills file

PostHog connector documentation as plain markdown, for use in AI agent contexts.

Get started

Context

Activate

Organizations

Workspaces

Resources

PostHog as a data source

Configuring PostHog as a Source

1. Add account access

2. Select streams

3. Configure data streams

4. Configure data source

5. Check your new source

Streams and Fields

Data Model

Use Cases for Data Analysis

1. Event volume by day

2. Top users by event activity (last 30 days)

Implementation Notes

Data Sync Behavior

Skills for agents

Download PostHog skills file

​Configuring PostHog as a Source

​1. Add account access

​2. Select streams

​3. Configure data streams

​4. Configure data source

​5. Check your new source

​Streams and Fields

​Data Model

​Use Cases for Data Analysis

​1. Event volume by day

​2. Top users by event activity (last 30 days)

​Implementation Notes

​Data Sync Behavior

​Skills for agents

Download PostHog skills file

Configuring PostHog as a Source

1. Add account access

2. Select streams

3. Configure data streams

4. Configure data source

5. Check your new source

Streams and Fields

Data Model

Use Cases for Data Analysis

1. Event volume by day

2. Top users by event activity (last 30 days)

Implementation Notes

Data Sync Behavior

Skills for agents