# PostHogOptions **SDK:** PostHog Node.js SDK ### Properties - **`disableGeoip`** (`boolean`) - Whether to disable GeoIP lookups - **`host`** (`string`) - PostHog API host, usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com' - **`flushAt`** (`number`) - The number of events to queue before sending to PostHog (flushing) - **`maxBatchSize`** (`number`) - The maximum number of queued messages to be flushed as part of a single batch (must be higher than `flushAt`) - **`disabled`** (`boolean`) - If set to true the SDK is essentially disabled (useful for local environments where you don't want to track anything) - **`defaultOptIn`** (`boolean`) - If set to false the SDK will not track until the `optIn` function is called. - **`disable_capture_url_hashes`** (`boolean`) - 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. - **`sendFeatureFlagEvent`** (`boolean`) - Whether to track that `getFeatureFlag` was called (used by Experiments) In posthog-node this is also the default for reads from an `evaluateFlags()` snapshot (`isEnabled()` / `getFlag()`). Pass `sendFeatureFlagEvents` to one of those reads, or to a single-flag getter, to override it for that call. - **`preloadFeatureFlags`** (`boolean`) - Whether to load feature flags when initialized or not - **`disableRemoteFeatureFlags`** (`boolean`) - 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). - **`disableRemoteConfig`** (`boolean`) - 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. - **`disableSurveys`** (`boolean`) - Whether to load surveys when initialized or not Requires the `PostHogSurveyProvider` to be used - **`bootstrap`** (`{ distinctId?: string; isIdentifiedId?: boolean; featureFlags?: Record; featureFlagPayloads?: Record; }`) - Option to bootstrap the library with given distinctId and feature flags - **`fetchRetryCount`** (`number`) - How many times we will retry HTTP requests - **`fetchRetryDelay`** (`number`) - The delay between HTTP request retries in milliseconds - **`requestTimeout`** (`number`) - Timeout in milliseconds for any calls - **`featureFlagsRequestTimeoutMs`** (`number`) - Timeout in milliseconds for feature flag calls - **`featureFlagsRequestMaxRetries`** (`number`) - How many times feature flag requests retry after a transient network error. Set to 0 to disable feature flag request retries. - **`remoteConfigRequestTimeoutMs`** (`number`) - Timeout in milliseconds for remote config calls - **`sessionExpirationTimeSeconds`** (`number`) - For Session Analysis how long before we expire a session in seconds - **`disableCompression`** (`boolean`) - Whether to disable GZIP compression - **`historicalMigration`** (`boolean`) - Special flag to indicate ingested data is for a historical migration - **`evaluationContexts`** (`readonly string[]`) - 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'] - **`evaluationEnvironments`** (`readonly string[]`) - Evaluation environments for feature flags. Deprecated: Use evaluationContexts instead. This property will be removed in a future version. - **`personProfiles`** (`"always" | "identified_only" | "never"`) - 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. - **`addTracingHeaders`** (`string[]`) - 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). - **`persistence`** (`"memory"`) - **`flushInterval`** (`number`) - The interval in milliseconds between periodic flushes - **`maxQueueSize`** (`number`) - The maximum number of cached messages either in memory or on the local storage (must be higher than `flushAt`) - **`readPostHogCookie`** (`boolean | { sessionIdleTimeoutSeconds?: number; optOutCapturingByDefault?: boolean; }`) - Lets the Express and NestJS integrations read the session ID, and the distinct ID of an identified user, from the posthog-js cookie when a request has neither tracing header. Turn it on only when posthog-js stores opt-out consent in a cookie, or when you do not use opt-out: the server cannot read an opt-out that posthog-js keeps in localStorage (its default). It needs cookie-backed posthog-js persistence (the default `localStorage+cookie`, or `cookie`), the default cookie name (no `persistence_name`), and the default `__ph_opt_in_out_` consent cookie name. Set `sessionIdleTimeoutSeconds` when posthog-js uses a custom `session_idle_timeout_seconds`, and set `optOutCapturingByDefault` when posthog-js uses `opt_out_capturing_by_default`, so a visitor with no consent cookie counts as opted out. A request sent right after `identify()` or `reset()` can still carry the previous identity, because posthog-js saves the cookie with a short delay. - **`metrics`** (`MetricsConfig`) - Configuration for the `posthog.metrics` API (count, gauge, histogram). Set `serviceName` so series can be filtered per service in the Metrics UI. - **`logs`** (`PostHogLogsConfig`) - Configuration for the `posthog.logger` / `posthog.captureLog` logs API. Logs are sent to PostHog Logs as OTLP records, with no OpenTelemetry packages needed. Each record carries the active span's `trace_id` / `span_id` and, inside `withContext`, the `distinctId` and `sessionId`, so logs join back to traces, persons and replays. `serviceName` defaults to the `traces` / `metrics` `serviceName`. - **`traces`** (`TracesConfig`) - Configuration for distributed tracing (`startSpan` / `withSpan`). Tracing is off until this is set; supplying it is all that's needed to turn it on. Set `serviceName` so spans can be attributed and grouped per service — the product aggregates operations by service and span name. `shutdown()` drains spans that have already ended, within the shutdown timeout; spans still open at that point are discarded. - **`secretKey`** (`string`) - Credential for fetching local feature flag definitions, decrypting remote config and sending email. Accepts either a Personal API Key (`phx_...`) or a Project Secret API Key (`phs_...`). Local evaluation can also use definitions from `flagDefinitionCacheProvider` without this credential. Remote config payload decryption via `getRemoteConfigPayload` still requires it. `emails.send` needs a Project Secret API Key with the `transactional_email:write` scope; set `enableLocalEvaluation: false` when the key is only for email. Prefer this over the deprecated `personalApiKey` option; when both are set, `secretKey` takes precedence. - **`personalApiKey`** (`string`) - Deprecated: Use `secretKey` instead. - **`appHost`** (`string`) - Your PostHog app host, such as `https://posthog.example.com`. `emails.send` sends there. Needed only when `host` is not PostHog Cloud, for example a reverse proxy, which must not receive the secret key. On PostHog Cloud, the client derives `https://us.posthog.com` or `https://eu.posthog.com` from `host`. - **`emailRequestTimeoutMs`** (`number`) - Timeout in milliseconds for each `emails.send` request. - **`emailRequestMaxRetries`** (`number`) - Number of retries for an `emails.send` after a network error, a rate limit, or an unavailable service. Every retry sends the same idempotency key. Set to 0 when a job runner already retries the send. - **`migratedFrom`** (`string`) - The provider your email moved from, such as `'resend'`. Sent with every `posthog.emails` request. - **`privacyMode`** (`boolean`) - Redact prompts, outputs and error details from every event that the PostHog AI integrations (`@posthog/ai`) capture with this client. Per-call privacy settings can only add redaction. Defaults to false. - **`enableExceptionAutocapture`** (`boolean`) - **`featureFlagsPollingInterval`** (`number`) - The interval in milliseconds between polls for refreshing feature flag definitions. Defaults to 30 seconds. Set to null to disable automatic polling. Definitions are still loaded on initialization; call reloadFeatureFlags() to refresh them manually. Until refreshed, local evaluation uses the last loaded definitions. - **`maxCacheSize`** (`number`) - **`fetch`** (`(url: string, options: PostHogFetchOptions) => Promise`) - **`enableLocalEvaluation`** (`boolean`) - **`flagDefinitionCacheProvider`** (`FlagDefinitionCacheProvider`) - 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. Without a secretKey or personalApiKey, this instance only reads cached definitions on each refresh; it does not call shouldFetchFlagDefinitions or publish definitions. With a credential, it uses the provider's fetch decision to coordinate fetching fresh definitions from PostHog and publishing them to the cache. This enables distributed coordination where only one worker fetches flags while others use cached data, reducing API calls and improving performance. - **`before_send`** (`BeforeSendFn | BeforeSendFn[]`) - 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. - **`custom_blocked_useragents`** (`string[]`) - Additional user agent strings to block from being tracked. These are combined with the default list of blocked user agents. - **`strictLocalEvaluation`** (`boolean`) - 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. - **`featureFlagsLogWarnings`** (`boolean`) - 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()`. - **`waitUntil`** (`(promise: Promise) => void`) - Provides the API to extend the lifetime of a serverless invocation until background work (like flushing analytics events) completes after the response is sent. - **`waitUntilDebounceMs`** (`number`) - Debounce interval in milliseconds for the `waitUntil`-based flush. After the last event is enqueued, the SDK waits this long before flushing. - **`waitUntilMaxWaitMs`** (`number`) - Maximum time in milliseconds to debounce before forcing a flush. Prevents starvation from rapid concurrent captures. - **`isServer`** (`boolean`) - Whether to attach the `$is_server: true` property to every captured event. - **`enableFullAiCapture`** (`boolean`) - Capture full AI content: PostHog AI wrapper events route through the dedicated AI capture endpoint, skip string truncation, and pass media (base64 / data URIs) through unredacted. Privacy mode always wins. Defaults to false. - **`exceptionRateLimiterRefillRate`** (`number`) - 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. - **`exceptionRateLimiterBucketSize`** (`number`) - 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.