# PostHog

PostHog is an open-source product analytics platform that helps teams understand user behavior. The Sling PostHog connector extracts data from the PostHog API, supporting projects, persons, events, cohorts, feature flags, insights, annotations, actions, session recordings, event definitions, and property definitions.

{% hint style="success" %}
**CLI Pro Required**: APIs require a [CLI Pro token](https://docs.slingdata.io/sling-cli/cli-pro) or [Platform Plan](https://docs.slingdata.io/sling-platform/platform).
{% endhint %}

## Setup

The following credentials are accepted:

**Secrets:**

* `api_key` **(required)** -> PostHog Personal API Key
* `project_id` **(required)** -> PostHog Project ID
* `host` (optional) -> PostHog host (defaults to `us.posthog.com`)

**Inputs (optional):**

* `anchor_date` -> Starting date for first sync (defaults to 1 year ago)

### Getting Your Credentials

1. Log in to [PostHog](https://us.posthog.com) (or your self-hosted instance)
2. Go to **Settings** → **Personal API Keys**
3. Click **Create personal API key**
4. Give it a label (e.g., "Sling Integration")
5. Under **Scopes**, select the **All access** preset (or grant read access to the endpoints you need)
6. Under **Organization & project access**, select **All access** (or choose specific projects)
7. Click **Create key** and copy the key (it starts with `phx_`)
8. Find your **Project ID** in **Settings** → **Project** (also visible in the URL: `https://us.posthog.com/project/<project_id>`)

{% hint style="info" %}
**Self-Hosted & EU Cloud:** If you use PostHog EU Cloud, set `host` to `eu.posthog.com`. For self-hosted instances, set `host` to your custom domain (e.g., `posthog.yourcompany.com`).
{% endhint %}

{% hint style="warning" %}
**Important:** Personal API keys grant access to your PostHog project data. Keep your key secure and never share it publicly.
{% endhint %}

### Using `sling conns`

Here are examples of setting a connection named `POSTHOG`. We must provide the `type=api` property:

{% code overflow="wrap" %}

```bash
sling conns set POSTHOG type=api spec=posthog secrets='{ api_key: "phx_your_personal_api_key", project_id: "12345" }'
```

{% endcode %}

### Environment Variable

See [here](https://docs.slingdata.io/sling-cli/environment#dot-env-file-.env.sling) to learn more about the `.env.sling` file.

{% code overflow="wrap" %}

```bash
export POSTHOG='{ type: api, spec: posthog, secrets: { api_key: "phx_your_personal_api_key", project_id: "12345" } }'
```

{% endcode %}

### Sling Env File YAML

See [here](https://docs.slingdata.io/sling-cli/environment#sling-env-file-env.yaml) to learn more about the sling `env.yaml` file.

```yaml
connections:
  POSTHOG:
    type: api
    spec: posthog
    secrets:
      api_key: "phx_your_personal_api_key"
      project_id: "12345"
```

## Replication

Here's an example replication configuration to sync PostHog data to a PostgreSQL database:

```yaml
source: POSTHOG
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: posthog.{stream_name}

streams:
  projects:
  persons:
  events:
    mode: incremental
  cohorts:
  feature_flags:
  insights:
  annotations:
    mode: incremental
  actions:
  session_recordings:
    mode: incremental
  event_definitions:
  property_definitions:
```

## Endpoints

| Endpoint               | Description                              | Incremental | Depends On |
| ---------------------- | ---------------------------------------- | ----------- | ---------- |
| `projects`             | Projects (teams) accessible to the user  | No          | —          |
| `persons`              | Persons (users) tracked in the project   | No          | —          |
| `events`               | Events captured in the project           | Yes         | —          |
| `cohorts`              | Cohort definitions                       | No          | —          |
| `feature_flags`        | Feature flag definitions                 | No          | —          |
| `insights`             | Saved insights (charts, funnels, trends) | No          | —          |
| `annotations`          | Annotations on charts                    | Yes         | —          |
| `actions`              | Actions (custom event groups)            | No          | —          |
| `session_recordings`   | Session recording metadata               | Yes         | —          |
| `event_definitions`    | Event name definitions and metadata      | No          | —          |
| `property_definitions` | Property definitions and metadata        | No          | —          |

To discover available endpoints:

```bash
sling conns discover POSTHOG
```

### Endpoint Details

**`projects`** — Returns all projects (teams) accessible to the authenticated user. Does not require a project ID scope.

**`persons`** — Returns all persons (users) tracked in the project, including custom properties and distinct IDs. Uses offset-based pagination.

**`events`** — Returns events captured in the project. Supports incremental sync via timestamp — after the first full extraction, subsequent runs only fetch events newer than the last synced timestamp. Ordered by timestamp descending.

**`cohorts`** — Returns all cohort definitions in the project, including group properties and membership criteria.

**`feature_flags`** — Returns all feature flag definitions, including rollout percentages and filter groups.

**`insights`** — Returns all saved insights (charts, funnels, trends, retention analyses) in the project, including query definitions and dashboard associations.

**`annotations`** — Returns all annotations in the project. Supports incremental sync via `updated_at` — subsequent runs only fetch annotations created or updated since the last sync.

**`actions`** — Returns all actions (custom event groups) defined in the project, including their step definitions.

**`session_recordings`** — Returns session recording metadata (not the actual recordings). Supports incremental sync via `start_time` — subsequent runs only fetch recordings started after the last sync date.

**`event_definitions`** — Returns all event name definitions and metadata in the project, including tags and verification status.

**`property_definitions`** — Returns all property definitions in the project, including property types and numerical flags.

## Incremental Sync

The `events`, `annotations`, and `session_recordings` endpoints support incremental sync:

* **First run:** Fetches all data from the `anchor_date` (default: 1 year ago) to now
* **Subsequent runs:** Only fetches data created or updated since the last sync

To customize the starting date:

```yaml
connections:
  POSTHOG:
    type: api
    spec: posthog
    secrets:
      api_key: "phx_your_key"
      project_id: "12345"
    inputs:
      anchor_date: "2024-01-01"
```

## Rate Limiting

The PostHog API enforces rate limits of 240 requests/minute for analytics endpoints and 480 requests/minute for CRUD endpoints.

The connector automatically:

* Uses conservative rate limiting (3 requests/second)
* Limits concurrency to 2 parallel requests
* Retries with exponential backoff on 429 (rate limit) responses with up to 5 retry attempts
* Retries with linear backoff on 5xx server errors with up to 3 retry attempts

If you are facing issues connecting, please reach out to us at <support@slingdata.io>, on [discord](https://discord.gg/q5xtaSNDvp) or open a Github Issue [here](https://github.com/slingdata-io/sling-cli/issues).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.slingdata.io/connections/api-connections/posthog.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.