Posthog.Client (posthog v0.4.1)

Low-level HTTP client for interacting with PostHog's API.

This module handles the direct HTTP communication with PostHog's API endpoints. It provides functions for:

  • Sending event capture requests
  • Processing batch events
  • Retrieving feature flag information

While this module can be used directly, it's recommended to use the higher-level functions in the Posthog module instead.

Configuration

The client uses the following configuration from your application:

config :posthog,
  api_url: "https://app.posthog.com",  # Required
  api_key: "phc_your_project_api_key", # Required
  json_library: Jason,                 # Optional (default: Jason)
  version: 3                          # Optional (default: 3)

API Endpoints

The client interacts with the following PostHog API endpoints:

  • /capture - For sending individual and batch events
  • /decide - For retrieving feature flag information

Error Handling

All functions return a result tuple:

  • {:ok, response} for successful requests
  • {:error, response} for failed requests with a response
  • {:error, term()} for other errors (network issues, etc.)

Examples 

# Capture an event
Posthog.Client.capture("page_view", %{distinct_id: "user_123"})

# Send batch events
events = [
  {"page_view", %{distinct_id: "user_123"}, nil},
  {"click", %{distinct_id: "user_123"}, DateTime.utc_now()}
]
Posthog.Client.batch(events)

# Get feature flags
Posthog.Client.feature_flags("user_123", groups: %{team: "engineering"})

Summary

Types

event()

Event name, can be either an atom or a binary string.

headers()

HTTP headers in the format expected by :hackney.

opts()

Options that can be passed to API requests.

properties()

Properties that can be attached to events or feature flag requests.

response()

Response from the PostHog API. Contains the status code, headers, and parsed JSON body (if any).

timestamp()

Timestamp for events. Can be a DateTime, NaiveDateTime, or ISO8601 string.

Functions

batch(events, opts)

Sends multiple events to PostHog in a single request.

batch(events, opts, headers)
build_event(event, properties, timestamp)

Builds an event payload for the PostHog API.

capture(event, params, opts)

Captures a single event in PostHog.

feature_flags(distinct_id, opts)

Retrieves feature flags for a given distinct ID.

Types

event()

@type event() :: atom() | binary()

Event name, can be either an atom or a binary string.

headers()

@type headers() :: [{binary(), binary()}]

HTTP headers in the format expected by :hackney.

opts()

@type opts() :: [
  headers: headers(),
  groups: map(),
  group_properties: map(),
  person_properties: map(),
  timestamp: timestamp()
]

Options that can be passed to API requests.

  • :headers - Additional HTTP headers to include in the request
  • :groups - Group properties for feature flag evaluation
  • :group_properties - Additional properties for groups
  • :person_properties - Properties for the person
  • :timestamp - Custom timestamp for events

properties()

@type properties() :: %{optional(String.t()) => term()}

Properties that can be attached to events or feature flag requests.

response()

@type response() :: %{status: pos_integer(), headers: headers(), body: map() | nil}

Response from the PostHog API. Contains the status code, headers, and parsed JSON body (if any).

timestamp()

@type timestamp() :: String.t()

Timestamp for events. Can be a DateTime, NaiveDateTime, or ISO8601 string.

Functions

batch(events, opts)

Sends multiple events to PostHog in a single request.

Parameters

  • events - List of event tuples in the format {event_name, properties, timestamp}
  • opts - Additional options (see opts/0)
  • headers - Additional HTTP headers

Examples 

events = [
  {"page_view", %{distinct_id: "user_123"}, nil},
  {"click", %{distinct_id: "user_123", properties: %{button: "signup"}}, DateTime.utc_now()}
]

Posthog.Client.batch(events)

batch(events, opts, headers)

@spec batch([{event(), properties(), timestamp()}], opts() | any(), headers()) ::
  {:ok, response()} | {:error, response() | term()}

build_event(event, properties, timestamp)

@spec build_event(event(), properties(), timestamp()) :: map()

Builds an event payload for the PostHog API.

Parameters

  • event - The name of the event
  • properties - Event properties
  • timestamp - Optional timestamp for the event

Examples 

build_event("page_view", %{distinct_id: "user_123"}, nil)
build_event("purchase", %{distinct_id: "user_123", price: 99.99}, DateTime.utc_now())

capture(event, params, opts)

@spec capture(event(), properties(), opts() | timestamp()) ::
  {:ok, response()} | {:error, response() | term()}

Captures a single event in PostHog.

Parameters

  • event - The name of the event (string or atom)
  • params - Event properties including :distinct_id
  • opts - Additional options (see opts/0)

Examples 

# Basic event
Posthog.Client.capture("page_view", %{distinct_id: "user_123"})

# Event with properties and timestamp
Posthog.Client.capture("purchase",
  %{
    distinct_id: "user_123",
    properties: %{product_id: "123", price: 99.99}
  },
  timestamp: DateTime.utc_now()
)

# Event with custom headers
Posthog.Client.capture("login",
  %{distinct_id: "user_123"},
  headers: [{"x-forwarded-for", "127.0.0.1"}]
)

feature_flags(distinct_id, opts)

@spec feature_flags(binary(), opts()) ::
  {:ok, Posthog.FeatureFlag.flag_response()} | {:error, response() | term()}

Retrieves feature flags for a given distinct ID.

Parameters

  • distinct_id - The unique identifier for the user
  • opts - Additional options (see opts/0)

Examples 

# Basic feature flags request
Posthog.Client.feature_flags("user_123")

# With group properties
Posthog.Client.feature_flags("user_123",
  groups: %{company: "company_123"},
  group_properties: %{company: %{industry: "tech"}}
)