PostHog Node.js SDK

SDK Version:

PostHog

Initialization methods

`PostHog`public

Initialize a new PostHog client instance.

Parameters

Name	Type
`apiKey`	`string`
Your PostHog project API key
`options?`	`PostHogOptions`
Configuration options for the client

Examples

JavaScript
// Basic initialization
const client = new PostHogBackendClient(
  'your-api-key',
  { host: 'https://app.posthog.com' }
)

JavaScript
// With personal API key
const client = new PostHogBackendClient(
  'your-api-key',
  {
    host: 'https://app.posthog.com',
    personalApiKey: 'your-personal-api-key'
  }
)

Returns

Type
`any`

`debug`public

Enable or disable debug logging.

Parameters

Name	Type
`enabled?`	`boolean`
Whether to enable debug logging

Examples

JavaScript
// Enable debug logging
client.debug(true)

JavaScript
// Disable debug logging
client.debug(false)

Returns

Type
`void`

`getLibraryVersion`public

Get the library version from package.json.

Examples

JavaScript
// Get version
const version = client.getLibraryVersion()
console.log(`Using PostHog SDK version: ${version}`)

Returns

Type
`string`

`getPersistedProperty`public

Get a persisted property value from memory storage.

Parameters

Name	Type
`key`	`PostHogPersistedProperty`
The property key to retrieve

Examples

JavaScript
// Get user ID
const userId = client.getPersistedProperty('userId')

JavaScript
// Get session ID
const sessionId = client.getPersistedProperty('sessionId')

Returns

	Type
Union of	`any`
Union of	`undefined`

`setPersistedProperty`public

Set a persisted property value in memory storage.

Parameters

Name	Type
`key`	`PostHogPersistedProperty`
The property key to set
`value`	`any \| null`
The value to store (null to remove)

Examples

JavaScript
// Set user ID
client.setPersistedProperty('userId', 'user_123')

JavaScript
// Set session ID
client.setPersistedProperty('sessionId', 'session_456')

Returns

Type
`void`

`shutdown`public

Shuts down the PostHog instance and ensures all events are sent.

Call shutdown() once before the process exits to ensure that all events have been sent and all promises have resolved. Do not use this function if you intend to keep using this PostHog instance after calling it. Use flush() for per-request cleanup instead.

Parameters

Name	Type
`shutdownTimeoutMs?`	`number`
Maximum time to wait for shutdown in milliseconds

Examples

JavaScript
// shutdown before process exit
process.on('SIGINT', async () => {
  await posthog.shutdown()
  process.exit(0)
})

Returns

Type
`Promise<void>`

Capture methods

`capture`public

Capture an event manually.

Parameters

Name	Type
`props`	`EventMessage`
The event properties

Examples

JavaScript
// Basic capture
client.capture({
  distinctId: 'user_123',
  event: 'button_clicked',
  properties: { button_color: 'red' }
})

Returns

Type
`void`

`captureImmediate`public

Capture an event immediately (synchronously).

Parameters

Name	Type
`props`	`EventMessage`
The event properties

Examples

JavaScript
// Basic immediate capture
await client.captureImmediate({
  distinctId: 'user_123',
  event: 'button_clicked',
  properties: { button_color: 'red' }
})

JavaScript
// With feature flags
await client.captureImmediate({
  distinctId: 'user_123',
  event: 'user_action',
  sendFeatureFlags: true
})

JavaScript
// With custom feature flags options
await client.captureImmediate({
  distinctId: 'user_123',
  event: 'user_action',
  sendFeatureFlags: {
    onlyEvaluateLocally: true,
    personProperties: { plan: 'premium' },
    groupProperties: { org: { tier: 'enterprise' } }
    flagKeys: ['flag1', 'flag2']
  }
})

Returns

Type
`Promise<void>`

Context methods

`getContext`public

Get the current context data.

Examples

JavaScript
// Get current context within a withContext block
posthog.withContext({ distinctId: 'user_123' }, () => {
  const context = posthog.getContext()
  console.log(context?.distinctId) // 'user_123'
})

Returns

	Type
Union of	`ContextData`
Union of	`undefined`

`withContext`public

Run a function with specific context that will be applied to all events captured within that context. It propagates the context to all subsequent calls down the call stack. Context properties like tags and sessionId will be automatically attached to all events. By default, nested contexts inherit from parent contexts. Use { fresh: true } to start with a clean context.

Parameters

Name	Type
`data`	`Partial<ContextData>`
Context data to apply (sessionId, distinctId, properties, enableExceptionAutocapture)
`fn`	`() => T`
Function to run with the context
`options?`	`ContextOptions`
Context options (fresh: true to start with clean context instead of inheriting)

Examples

JavaScript
posthog.withContext({ distinctId: 'user_123' }, () => {
  posthog.capture({ event: 'button clicked' })
})

Returns

Type
`T`

Error tracking methods

`captureException`public

Capture an error exception as an event.

Parameters

Name	Type
`error`	`unknown`
The error to capture
`distinctId?`	`string`
Optional user distinct ID
`additionalProperties?`	`Record<string \| number, any>`
Optional additional properties to include
`uuid?`	`EventMessage['uuid']`

Examples

JavaScript
// Capture an error with user ID
try {
  // Some risky operation
  riskyOperation()
} catch (error) {
  client.captureException(error, 'user_123')
}

JavaScript
// Capture with additional properties
try {
  apiCall()
} catch (error) {
  client.captureException(error, 'user_123', {
    endpoint: '/api/users',
    method: 'POST',
    status_code: 500
  })
}

Returns

Type
`void`

`captureExceptionImmediate`public

Capture an error exception as an event immediately (synchronously).

Parameters

Name	Type
`error`	`unknown`
The error to capture
`distinctId?`	`string`
Optional user distinct ID
`additionalProperties?`	`Record<string \| number, any>`
Optional additional properties to include

Examples

JavaScript
// Capture an error immediately with user ID
try {
  // Some risky operation
  riskyOperation()
} catch (error) {
  await client.captureExceptionImmediate(error, 'user_123')
}

JavaScript
// Capture with additional properties
try {
  apiCall()
} catch (error) {
  await client.captureExceptionImmediate(error, 'user_123', {
    endpoint: '/api/users',
    method: 'POST',
    status_code: 500
  })
}

Returns

Type
`Promise<void>`

Feature flags methods

`getAllFlags`public

Get all feature flag values for a specific user.

Parameters

Name	Type
`options?`	`AllFlagsOptions`
Optional configuration for flag evaluation

Examples

JavaScript
// Get all flags for a user
const allFlags = await client.getAllFlags('user_123')
console.log('User flags:', allFlags)
// Output: { 'flag-1': 'variant-a', 'flag-2': false, 'flag-3': 'variant-b' }

JavaScript
// With specific flag keys
const specificFlags = await client.getAllFlags('user_123', {
  flagKeys: ['flag-1', 'flag-2']
})

JavaScript
// With groups and properties
const orgFlags = await client.getAllFlags('user_123', {
  groups: { organization: 'acme-corp' },
  personProperties: { plan: 'enterprise' }
})

Returns

Type
`Promise<Record<string, FeatureFlagValue>>`

`getAllFlagsAndPayloads`public

Get all feature flag values and payloads for a specific user.

Parameters

Name	Type
`options?`	`AllFlagsOptions`
Optional configuration for flag evaluation

Examples

JavaScript
// Get all flags and payloads for a user
const result = await client.getAllFlagsAndPayloads('user_123')
console.log('Flags:', result.featureFlags)
console.log('Payloads:', result.featureFlagPayloads)

JavaScript
// With specific flag keys
const result = await client.getAllFlagsAndPayloads('user_123', {
  flagKeys: ['flag-1', 'flag-2']
})

JavaScript
// Only evaluate locally
const result = await client.getAllFlagsAndPayloads('user_123', {
  onlyEvaluateLocally: true
})

Returns

Type
`Promise<PostHogFlagsAndPayloadsResponse>`

`getFeatureFlag`public

Get the value of a feature flag for a specific user.

Parameters

Name	Type
`key`	`string`
The feature flag key
`distinctId`	`string`
The user's distinct ID
`options?`	`{ groups?: Record<string, string>; personProperties?: Record<string, string>; groupProperties?: Record<string, Record<string, string>>; onlyEvaluateLocally?: boolean; sendFeatureFlagEvents?: boolean; disableGeoip?: boolean; }`
Optional configuration for flag evaluation

Examples

JavaScript
// Basic feature flag check
const flagValue = await client.getFeatureFlag('new-feature', 'user_123')
if (flagValue === 'variant-a') {
  // Show variant A
} else if (flagValue === 'variant-b') {
  // Show variant B
} else {
  // Flag is disabled or not found
}

JavaScript
// With groups and properties
const flagValue = await client.getFeatureFlag('org-feature', 'user_123', {
  groups: { organization: 'acme-corp' },
  personProperties: { plan: 'enterprise' },
  groupProperties: { organization: { tier: 'premium' } }
})

JavaScript
// Only evaluate locally
const flagValue = await client.getFeatureFlag('local-flag', 'user_123', {
  onlyEvaluateLocally: true
})

Returns

	Type
Union of	`Promise<FeatureFlagValue`
Union of	`undefined>`

`getFeatureFlagPayload`public

Get the payload for a feature flag.

Parameters

Name	Type
`key`	`string`
The feature flag key
`distinctId`	`string`
The user's distinct ID
`matchValue?`	`FeatureFlagValue`
Optional match value to get payload for
`options?`	`{ groups?: Record<string, string>; personProperties?: Record<string, string>; groupProperties?: Record<string, Record<string, string>>; onlyEvaluateLocally?: boolean; sendFeatureFlagEvents?: boolean; disableGeoip?: boolean; }`
Optional configuration for flag evaluation

Examples

JavaScript
// Get payload for a feature flag
const payload = await client.getFeatureFlagPayload('flag-key', 'user_123')
if (payload) {
  console.log('Flag payload:', payload)
}

JavaScript
// Get payload with specific match value
const payload = await client.getFeatureFlagPayload('flag-key', 'user_123', 'variant-a')

JavaScript
// With groups and properties
const payload = await client.getFeatureFlagPayload('org-flag', 'user_123', undefined, {
  groups: { organization: 'acme-corp' },
  personProperties: { plan: 'enterprise' }
})

Returns

	Type
Union of	`Promise<JsonType`
Union of	`undefined>`

`getFeatureFlagResult`public

Get the result of evaluating a feature flag, including its value and payload. This is more efficient than calling getFeatureFlag and getFeatureFlagPayload separately when you need both.

Parameters

Name	Type
`key`	`string`
The feature flag key
`options?`	`FlagEvaluationOptions`
Optional configuration for flag evaluation

Examples

JavaScript
// Get flag result
const result = await client.getFeatureFlagResult('my-flag', 'user_123')
if (result) {
  console.log('Flag enabled:', result.enabled)
  console.log('Variant:', result.variant)
  console.log('Payload:', result.payload)
}

JavaScript
// With groups and properties
const result = await client.getFeatureFlagResult('org-feature', 'user_123', {
  groups: { organization: 'acme-corp' },
  personProperties: { plan: 'enterprise' }
})

Returns

	Type
Union of	`Promise<FeatureFlagResult`
Union of	`undefined>`

`getRemoteConfigPayload`public

Get the remote config payload for a feature flag.

Parameters

Name	Type
`flagKey`	`string`
The feature flag key

Examples

JavaScript
// Get remote config payload
const payload = await client.getRemoteConfigPayload('flag-key')
if (payload) {
  console.log('Remote config payload:', payload)
}

Returns

	Type
Union of	`Promise<JsonType`
Union of	`undefined>`

`isFeatureEnabled`public

Check if a feature flag is enabled for a specific user.

Parameters

Name	Type
`key`	`string`
The feature flag key
`distinctId`	`string`
The user's distinct ID
`options?`	`{ groups?: Record<string, string>; personProperties?: Record<string, string>; groupProperties?: Record<string, Record<string, string>>; onlyEvaluateLocally?: boolean; sendFeatureFlagEvents?: boolean; disableGeoip?: boolean; }`
Optional configuration for flag evaluation

Examples

JavaScript
// Basic feature flag check
const isEnabled = await client.isFeatureEnabled('new-feature', 'user_123')
if (isEnabled) {
  // Feature is enabled
  console.log('New feature is active')
} else {
  // Feature is disabled
  console.log('New feature is not active')
}

JavaScript
// With groups and properties
const isEnabled = await client.isFeatureEnabled('org-feature', 'user_123', {
  groups: { organization: 'acme-corp' },
  personProperties: { plan: 'enterprise' }
})

Returns

	Type
Union of	`Promise<boolean`
Union of	`undefined>`

`isLocalEvaluationReady`public

Check if local evaluation of feature flags is ready.

Examples

JavaScript
// Check if ready
if (client.isLocalEvaluationReady()) {
  // Local evaluation is ready, can evaluate flags locally
  const flag = await client.getFeatureFlag('flag-key', 'user_123')
} else {
  // Local evaluation not ready, will use remote evaluation
  const flag = await client.getFeatureFlag('flag-key', 'user_123')
}

Returns

Type
`boolean`

`overrideFeatureFlags`public

Override feature flags locally. Useful for testing and local development. Overridden flags take precedence over both local evaluation and remote evaluation.

Parameters

Name	Type
`overrides`	`OverrideFeatureFlagsOptions`
Flag overrides configuration

Examples

JavaScript
// Clear all overrides
client.overrideFeatureFlags(false)

// Enable a list of flags (sets them to true)
client.overrideFeatureFlags(['flag-a', 'flag-b'])

// Set specific flag values/variants
client.overrideFeatureFlags({ 'my-flag': 'variant-a', 'other-flag': true })

// Set both flags and payloads
client.overrideFeatureFlags({
  flags: { 'my-flag': 'variant-a' },
  payloads: { 'my-flag': { discount: 20 } }
})

Returns

Type
`void`

`reloadFeatureFlags`public

Reload feature flag definitions from the server for local evaluation.

Examples

JavaScript
// Force reload of feature flags
await client.reloadFeatureFlags()
console.log('Feature flags reloaded')

JavaScript
// Reload before checking a specific flag
await client.reloadFeatureFlags()
const flag = await client.getFeatureFlag('flag-key', 'user_123')

Returns

Type
`Promise<void>`

`waitForLocalEvaluationReady`public

Wait for local evaluation of feature flags to be ready.

Parameters

Name	Type
`timeoutMs?`	`number`
Timeout in milliseconds (default: 30000)

Examples

JavaScript
// Wait for local evaluation
const isReady = await client.waitForLocalEvaluationReady()
if (isReady) {
  console.log('Local evaluation is ready')
} else {
  console.log('Local evaluation timed out')
}

JavaScript
// Wait with custom timeout
const isReady = await client.waitForLocalEvaluationReady(10000) // 10 seconds

Returns

Type
`Promise<boolean>`

Identification methods

`alias`public

Create an alias to link two distinct IDs together.

Parameters

Name	Type
`data`	`{ distinctId: string; alias: string; disableGeoip?: boolean; }`
The alias data containing distinctId and alias

Examples

JavaScript
// Link an anonymous user to an identified user
client.alias({
  distinctId: 'anonymous_123',
  alias: 'user_456'
})

Returns

Type
`void`

`aliasImmediate`public

Create an alias to link two distinct IDs together immediately (synchronously).

Parameters

Name	Type
`data`	`{ distinctId: string; alias: string; disableGeoip?: boolean; }`
The alias data containing distinctId and alias

Examples

JavaScript
// Link an anonymous user to an identified user immediately
await client.aliasImmediate({
  distinctId: 'anonymous_123',
  alias: 'user_456'
})

Returns

Type
`Promise<void>`

`getCustomUserAgent`public

Get the custom user agent string for this client.

Examples

JavaScript
// Get user agent
const userAgent = client.getCustomUserAgent()
// Returns: "posthog-node/5.7.0"

Returns

Type
`string`

`groupIdentify`public

Create or update a group and its properties.

Parameters

Name	Type
`{ groupType, groupKey, properties, distinctId, disableGeoip }`	`GroupIdentifyMessage`

Examples

JavaScript
// Create a company group
client.groupIdentify({
  groupType: 'company',
  groupKey: 'acme-corp',
  properties: {
    name: 'Acme Corporation',
    industry: 'Technology',
    employee_count: 500
  },
  distinctId: 'user_123'
})

JavaScript
// Update organization properties
client.groupIdentify({
  groupType: 'organization',
  groupKey: 'org-456',
  properties: {
    plan: 'enterprise',
    region: 'US-West'
  }
})

Returns

Type
`void`

`identify`public

Identify a user and set their properties.

Parameters

Name	Type
`{ distinctId, properties, disableGeoip }`	`IdentifyMessage`

Examples

JavaScript
// Basic identify with properties
client.identify({
  distinctId: 'user_123',
  properties: {
    name: 'John Doe',
    email: 'john@example.com',
    plan: 'premium'
  }
})

JavaScript
// Using $set and $set_once
client.identify({
  distinctId: 'user_123',
  properties: {
    $set: { name: 'John Doe', email: 'john@example.com' },
    $set_once: { first_login: new Date().toISOString() }
    $anon_distinct_id: 'anonymous_user_456'
  }
})

Returns

Type
`void`

`identifyImmediate`public

Identify a user and set their properties immediately (synchronously).

Parameters

Name	Type
`{ distinctId, properties, disableGeoip }`	`IdentifyMessage`

Examples

JavaScript
// Basic immediate identify
await client.identifyImmediate({
  distinctId: 'user_123',
  properties: {
    name: 'John Doe',
    email: 'john@example.com'
  }
})

Returns

Type
`Promise<void>`

Privacy methods

`disable`public

Disable the PostHog client (opt-out).

Examples

JavaScript
// Disable client
await client.disable()
// Client is now disabled and will not capture events

Returns

Type
`Promise<void>`

`enable`public

Enable the PostHog client (opt-in).

Examples

JavaScript
// Enable client
await client.enable()
// Client is now enabled and will capture events

Returns

Type
`Promise<void>`

Other methods

`getLibraryId`public

Examples

JavaScript
// Generated example for getLibraryId
posthog.getLibraryId();

Returns

Type
`string`

`enterContext`public

Set context without a callback wrapper.

Uses AsyncLocalStorage.enterWith() to attach context to the current async execution context. The context lives until that async context ends.

Must be called in the same async scope that makes PostHog calls. Calling this outside a request-scoped async context will leak context across unrelated work. Prefer withContext() when you can wrap code in a callback — it creates an isolated scope that cleans up automatically.

Parameters

Name	Type
`data`	`Partial<ContextData>`
Context data to apply (distinctId, sessionId, properties)
`options?`	`ContextOptions`
Context options (fresh: true to start with clean context instead of inheriting)

Examples

JavaScript
// Generated example for enterContext
posthog.enterContext();

Returns

Type
`void`

`flush`public

Examples

JavaScript
// Generated example for flush
posthog.flush();

Returns

Type
`Promise<void>`

`prepareEventMessage`public

Parameters

Name	Type
`props`	`EventMessage`

Examples

JavaScript
// Generated example for prepareEventMessage
posthog.prepareEventMessage();

Returns

Type
`Promise<{ distinctId: string; event: string; properties: PostHogEventProperties; options: PostHogCaptureOptions; }>`

`fetch`public

Parameters

Name	Type
`url`	`string`
`options`	`PostHogFetchOptions`

Examples

JavaScript
// Generated example for fetch
posthog.fetch();

Returns

Type
`Promise<PostHogFetchResponse>`

`getSurveysStateless`public

** SURVEYS *

Examples

JavaScript
// Generated example for getSurveysStateless
posthog.getSurveysStateless();

Returns

Type
`Promise<SurveyResponse['surveys']>`

`on`public

Parameters

Name	Type
`event`	`string`
`cb`	`(...args: any[]) => void`

Examples

JavaScript
// Generated example for on
posthog.on();

Returns

Type
`() => void`

`optIn`public

Examples

JavaScript
// Generated example for optIn
posthog.optIn();

Returns

Type
`Promise<void>`

`optOut`public

Examples

JavaScript
// Generated example for optOut
posthog.optOut();

Returns

Type
`Promise<void>`

`register`public

Parameters

Name	Type
`properties`	`PostHogEventProperties`

Examples

JavaScript
// Generated example for register
posthog.register();

Returns

Type
`Promise<void>`

`unregister`public

Parameters

Name	Type
`property`	`string`

Examples

JavaScript
// Generated example for unregister
posthog.unregister();

Returns

Type
`Promise<void>`

PostHog Node.js SDK

PostHog

Initialization methods

PostHogpublic

Parameters

Examples

Returns

debugpublic

Parameters

Examples

Returns

getLibraryVersionpublic

Examples

Returns

getPersistedPropertypublic

Parameters

Examples

Returns

setPersistedPropertypublic

Parameters

Examples

Returns

shutdownpublic

Parameters

Examples

Returns

Capture methods

capturepublic

Parameters

Examples

Returns

captureImmediatepublic

Parameters

Examples

Returns

Context methods

getContextpublic

Examples

Returns

withContextpublic

Parameters

Examples

Returns

Error tracking methods

captureExceptionpublic

Parameters

Examples

Returns

captureExceptionImmediatepublic

Parameters

Examples

Returns

Feature flags methods

getAllFlagspublic

Parameters

Examples

Returns

getAllFlagsAndPayloadspublic

Parameters

Examples

Returns

getFeatureFlagpublic

Parameters

Examples

Returns

getFeatureFlagPayloadpublic

Parameters

Examples

Returns

getFeatureFlagResultpublic

Parameters

Examples

Returns

getRemoteConfigPayloadpublic

Parameters

Examples

Returns

isFeatureEnabledpublic

Parameters

Examples

`PostHog`public

`debug`public

`getLibraryVersion`public

`getPersistedProperty`public

`setPersistedProperty`public

`shutdown`public

`capture`public

`captureImmediate`public

`getContext`public

`withContext`public

`captureException`public

`captureExceptionImmediate`public

`getAllFlags`public

`getAllFlagsAndPayloads`public

`getFeatureFlag`public

`getFeatureFlagPayload`public

`getFeatureFlagResult`public

`getRemoteConfigPayload`public

`isFeatureEnabled`public

`isLocalEvaluationReady`public

`overrideFeatureFlags`public

`reloadFeatureFlags`public

`waitForLocalEvaluationReady`public

`alias`public

`aliasImmediate`public

`getCustomUserAgent`public

`groupIdentify`public

`identify`public

`identifyImmediate`public

`disable`public

`enable`public

`getLibraryId`public

`enterContext`public

`flush`public

`prepareEventMessage`public

`fetch`public

`getSurveysStateless`public

`on`public