PostHogOptions

Whether to disable GeoIP lookups

PostHog API host, usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com'

The number of events to queue before sending to PostHog (flushing)

The maximum number of queued messages to be flushed as part of a single batch (must be higher than flushAt)

If set to true the SDK is essentially disabled (useful for local environments where you don't want to track anything)

If set to false the SDK will not track until the optIn function is called.

Whether to strip URL fragments (#...) from automatically captured URL fields. Disabled by default for backwards compatibility. Set to true to strip hashes from:

• $current_url on automatically captured browser events, including $pageview
• $initial_current_url
• $session_entry_url
• $elements[*].attr__href and $external_click_url for autocapture and dead-click autocapture
• Next.js Pages Router $pageview $current_url
• web vitals $current_url
• logs url.full
• conversations current_url and request_url
• session replay rrweb meta/custom-event href URLs
• heatmap data URLs

If your SPA relies on hash-based routes for analytics, enabling this is a breaking behavior change. If you want to capture hashes selectively, leave this as false and use before_send to remove sensitive hash values before events are sent.

Whether to track that getFeatureFlag was called (used by Experiments)

Whether to load feature flags when initialized or not

Advanced: whether to disable fetching and evaluating feature flags from PostHog entirely.

When set to true, reloadFeatureFlags() and the reloads triggered by identify(), group(), setPersonPropertiesForFlags() and reset() become no-ops, and any request to the flags endpoint that still goes out (e.g. to fetch remote config or surveys) carries disable_flags: true so the server skips flag evaluation. Flag values must be supplied via the bootstrap option or updateFlags() instead; getFeatureFlag() and related methods keep working against those values. Until updateFlags() runs, reads return their not-loaded defaults, so use bootstrap for any flags needed at startup. Equivalent to the web SDK's advanced_disable_feature_flags.

Note: surveys gated on feature flags will not evaluate unless the survey targeting flags are also provided via updateFlags(). This option cannot be toggled at runtime. posthog-node inherits this option but does not implement it (no-op).

Whether to load remote config when initialized or not Deprecated: Remote config is now always loaded and this option is a no-op. It will be removed in a future version.

Whether to load surveys when initialized or not Requires the PostHogSurveyProvider to be used

Option to bootstrap the library with given distinctId and feature flags

How many times we will retry HTTP requests

The delay between HTTP request retries in milliseconds

Timeout in milliseconds for any calls

Timeout in milliseconds for feature flag calls

How many times feature flag requests retry after a transient network error. Set to 0 to disable feature flag request retries.

Timeout in milliseconds for remote config calls

For Session Analysis how long before we expire a session in seconds

Whether to disable GZIP compression

Special flag to indicate ingested data is for a historical migration

Evaluation contexts for feature flags. When set, only feature flags that have at least one matching evaluation tag will be evaluated for this SDK instance. Feature flags with no evaluation tags will always be evaluated.

Examples: ['production', 'web', 'mobile'] Evaluation contexts for feature flags. When set, only feature flags that have at least one matching evaluation tag will be evaluated for this SDK instance. Feature flags with no evaluation tags will always be evaluated.

Examples: ['production', 'backend', 'api']

Evaluation environments for feature flags. Deprecated: Use evaluationContexts instead. This property will be removed in a future version.

Determines when to create Person Profiles for users.

• 'always': Always create a person profile for every user (anonymous and identified).
• 'identified_only': Only create a person profile when the user is identified via identify(), alias(), or group(). Events captured before identification will NOT have person profiles and will be anonymous events.
• 'never': Never create person profiles. identify(), alias(), and group() will be no-ops.

A list of hostnames for which to inject PostHog tracing headers (X-POSTHOG-DISTINCT-ID, X-POSTHOG-SESSION-ID) on outgoing fetch requests.

Use this to link requests made from your app to session replays and LLM traces in PostHog. When set, the global fetch is patched on initialization and the headers are added to requests whose hostname matches one of the entries.

Requires the SDK to wire up patchFetchForTracingHeaders against this option (currently supported in posthog-react-native).

The interval in milliseconds between periodic flushes

The maximum number of cached messages either in memory or on the local storage (must be higher than flushAt)

Configuration for the posthog.metrics API (count, gauge, histogram). Set serviceName so series can be filtered per service in the Metrics UI.

Credential that enables local feature flag evaluation and remote config.

Accepts either a Personal API Key (phx_...) or a Project Secret API Key (phs_...). When provided, the client can evaluate feature flags locally and decrypt remote config payloads via getRemoteConfigPayload. Prefer this over the deprecated personalApiKey option; when both are set, secretKey takes precedence.

Deprecated: Use secretKey instead.

Optional cache provider for feature flag definitions.

Allows custom caching strategies (Redis, database, etc.) for flag definitions in multi-worker environments. If not provided, defaults to in-memory cache.

This enables distributed coordination where only one worker fetches flags while others use cached data, reducing API calls and improving performance.

Allows modification or dropping of events before they're sent to PostHog. If an array is provided, the functions are run in order. If a function returns null, the event will be dropped.

Additional user agent strings to block from being tracked. These are combined with the default list of blocked user agents.

When enabled, all feature flag evaluations will use local evaluation only, never falling back to server-side evaluation. This prevents unexpected server requests and associated costs when using local evaluation.

Flags that cannot be evaluated locally (e.g., those with experience continuity) will return undefined instead of making a server request.

Controls whether FeatureFlagEvaluations filter helpers (onlyAccessed() and only()) log warnings when their input is unexpected — for example, calling onlyAccessed() before accessing any flags, or passing unknown keys to only().

Provides the API to extend the lifetime of a serverless invocation until background work (like flushing analytics events) completes after the response is sent.

Debounce interval in milliseconds for the waitUntil-based flush. After the last event is enqueued, the SDK waits this long before flushing.

Maximum time in milliseconds to debounce before forcing a flush. Prevents starvation from rapid concurrent captures.

Whether to attach the $is_server: true property to every captured event.

ADVANCED: alters the refill rate for the error tracking rate limiter's token bucket. Normally only altered alongside PostHog support guidance. Accepts values between 0 and 100.

ADVANCED: alters the bucket size for the error tracking rate limiter's token bucket. Normally only altered alongside PostHog support guidance. Accepts values between 0 and 100.