Instrument Integration

AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt

PostHog Node.js SDK

PostHog Node.js SDK allows you to capture events and send them to PostHog from your Node.js applications.

Categories

• Initialization

• Identification

• Capture

• Error tracking

• Privacy

• Feature flags

• Traces

• Context

PostHog

Other methods

getLibraryId()

Release Tag: public

Returns

• string

Examples

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

enterContext()

Release Tag: 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

• data (Partial<ContextData>) - Context data to apply (distinctId, sessionId, properties)

• options? (ContextOptions) - Context options (fresh: true to start with clean context instead of inheriting)

Returns

• void

Examples

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

flush()

Release Tag: public

Returns

• Promise<void>

Examples

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

prepareEventMessage()

Release Tag: public

Parameters

• props (EventMessage)

Returns

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

Examples

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

fetch()

Release Tag: public

Parameters

• url (string)

• options (PostHogFetchOptions)

Returns

• Promise<PostHogFetchResponse>

Examples

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

getSurveysStateless()

Release Tag: public

• ** SURVEYS *

Returns

• Promise<SurveyResponse['surveys']>

Examples

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

on()

Release Tag: public

Parameters

• event (string)

• cb ((...args: any[]) => void)

Returns

• () => void

Examples

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

optIn()

Release Tag: public

Returns

• Promise<void>

Examples

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

optOut()

Release Tag: public

Returns

• Promise<void>

Examples

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

register()

Release Tag: public

Parameters

• properties (PostHogEventProperties)

Returns

• Promise<void>

Examples

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

unregister()

Release Tag: public

Parameters

• property (string)

Returns

• Promise<void>

Examples

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

Initialization methods

PostHog()

Release Tag: public

Initialize a new PostHog client instance.

Parameters

• apiKey (string) - Your PostHog project API key

• options? (PostHogOptions) - Configuration options for the client

Returns

• any

Examples

Basic initialization

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

With a secret key (Personal API Key or Project Secret API Key) for local evaluation

// With a secret key (Personal API Key or Project Secret API Key) for local evaluation
const client = new PostHogBackendClient(
  'your-api-key',
  {
    host: 'https://app.posthog.com',
    secretKey: 'your-secret-key'
  }
)

debug()

Release Tag: public

Enable or disable debug logging.

Parameters

• enabled? (boolean) - Whether to enable debug logging

Returns

• void

Examples

Enable debug logging

// Enable debug logging
client.debug(true)

Disable debug logging

// Disable debug logging
client.debug(false)

getLibraryVersion()

Release Tag: public

Get the library version from package.json.

Returns

• string

Examples

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

getPersistedProperty()

Release Tag: public

Get a persisted property value from memory storage.

Parameters

• key (PostHogPersistedProperty) - The property key to retrieve

Returns

Union of:

• any

• undefined

Examples

Get user ID

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

Get session ID

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

setPersistedProperty()

Release Tag: public

Set a persisted property value in memory storage.

Parameters

• key (PostHogPersistedProperty) - The property key to set

• value (any | null) - The value to store (null to remove)

Returns

• void

Examples

Set user ID

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

Set session ID

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

shutdown()

Release Tag: 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

• shutdownTimeoutMs? (number) - Maximum time to wait for shutdown in milliseconds

Returns

• Promise<void>

Examples

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

Identification methods

alias()

Release Tag: public

Create an alias to link two distinct IDs together.

Parameters

• data ({ distinctId: string; alias: string; disableGeoip?: boolean; }) - The alias data containing distinctId and alias

Returns

• void

Examples

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

aliasImmediate()

Release Tag: public

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

Parameters

• data ({ distinctId: string; alias: string; disableGeoip?: boolean; }) - The alias data containing distinctId and alias

Returns

• Promise<void>

Examples

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

getCustomUserAgent()

Release Tag: public

Get the custom user agent string for this client.

Returns

• string

Examples

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

groupIdentify()

Release Tag: public

Create or update a group and its properties.

Parameters

• { groupType, groupKey, properties, distinctId, disableGeoip } (any)

• input (GroupIdentifyMessage)

Returns

• void

Examples

Create a company group

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

Update organization properties

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

groupIdentifyImmediate()

Release Tag: public

Create or update a group and its properties immediately (synchronously).

Parameters

• { groupType, groupKey, properties, distinctId, disableGeoip, } (any)

• input (GroupIdentifyMessage)

Returns

• Promise<void>

Examples

// Immediately create or update a company group
await client.groupIdentifyImmediate({
  groupType: 'company',
  groupKey: 'acme-corp',
  properties: {
    name: 'Acme Corporation',
    industry: 'Technology',
    employee_count: 500
  }
})

identify()

Release Tag: public

Identify a user and set their properties.

Parameters

• { distinctId, properties, disableGeoip } (any)

• input (IdentifyMessage)

Returns

• void

Examples

Basic identify with properties

// Basic identify with properties
client.identify({
  distinctId: 'user_123',
  properties: {
    name: 'John Doe',
    email: '[email protected]',
    plan: 'premium'
  }
})

Using $set and $set_once

// Using $set and $set_once
client.identify({
  distinctId: 'user_123',
  properties: {
    $set: { name: 'John Doe', email: '[email protected]' },
    $set_once: { first_login: new Date().toISOString() }
    $anon_distinct_id: 'anonymous_user_456'
  }
})

identifyImmediate()

Release Tag: public

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

Parameters

• { distinctId, properties, disableGeoip } (any)

• input (IdentifyMessage)

Returns

• Promise<void>

Examples

// Basic immediate identify
await client.identifyImmediate({
  distinctId: 'user_123',
  properties: {
    name: 'John Doe',
    email: '[email protected]'
  }
})

setPersonProperties()

Release Tag: public

Set properties on a person profile.

Parameters

• { distinctId, properties, propertiesOnce } (any)

• input (SetPersonPropertiesMessage)

Returns

• void

Examples

client.setPersonProperties({
  distinctId: 'user_123',
  properties: { plan: 'premium' },
  propertiesOnce: { first_seen: '2026-06-15' }
})

unsetPersonProperties()

Release Tag: public

Remove properties from a person profile.

Parameters

• { distinctId, properties } (any)

• input (UnsetPersonPropertiesMessage)

Returns

• void

Examples

client.unsetPersonProperties({
  distinctId: 'user_123',
  properties: ['plan', 'email']
})

Capture methods

capture()

Release Tag: public

Capture an event manually.

Parameters

• props (EventMessage) - The event properties

Returns

• void

Examples

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

captureAi()

Release Tag: public

Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Delivery is async, and no redaction or truncation is applied to the payload.

Parameters

• props (EventMessage) - The event properties

Returns

Union of:

• string

• undefined

Examples

// Generated example for captureAi
posthog.captureAi();

captureAiImmediate()

Release Tag: public

Capture an AI event on the dedicated AI capture endpoint, resolving after the send completes. Use in short-lived processes (serverless) where the runtime may freeze before a background flush runs.

Parameters

• props (EventMessage) - The event properties

Returns

Union of:

• Promise<string

• undefined>

Examples

// Generated example for captureAiImmediate
posthog.captureAiImmediate();

captureImmediate()

Release Tag: public

Capture an event immediately (synchronously).

Parameters

• props (EventMessage) - The event properties

Returns

• Promise<void>

Examples

Basic immediate capture

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

With feature flags

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

With custom feature flags options

// 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']
  }
})

Error tracking methods

captureException()

Release Tag: public

Capture an error exception as an event.

Parameters

• 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']) - Optional event UUID

• flags? (FeatureFlagEvaluations) - Optional FeatureFlagEvaluations snapshot to attach the same flag context as your other events

Returns

• void

Examples

Capture an error with user ID

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

Capture with additional properties

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

captureExceptionImmediate()

Release Tag: public

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

Parameters

• error (unknown) - The error to capture

• distinctId? (string) - Optional user distinct ID

• additionalProperties? (Record<string | number, any>) - Optional additional properties to include

• flags? (FeatureFlagEvaluations) - Optional FeatureFlagEvaluations snapshot to attach the same flag context as your other events

Returns

• Promise<void>

Examples

Capture an error immediately with user ID

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

Capture with additional properties

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

Privacy methods

disable()

Release Tag: public

Disable the PostHog client (opt-out).

Returns

• Promise<void>

Examples

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

enable()

Release Tag: public

Enable the PostHog client (opt-in).

Returns

• Promise<void>

Examples

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

Feature flags methods

evaluateFlags()

Release Tag: public

Evaluate all feature flags for a user in a single call and return a snapshot. Branch on .isEnabled() / .getFlag(), then pass the same snapshot to capture() via the flags option so the captured event carries the exact flag values the code branched on. Prefer this over repeated isFeatureEnabled() / getFeatureFlag() calls and over capture({ sendFeatureFlags: true }) — it consolidates flag evaluation into a single /flags request per incoming request. Local evaluation is transparent. When the poller can resolve a flag from cached definitions, no network call is made and the snapshot's $feature_flag_called events are tagged locally_evaluated: true. A requested key missing from local definitions is included in a /flags fallback unless onlyEvaluateLocally is true. Locally resolved values remain authoritative when remote results are merged. In particular, a cached inactive definition is a conclusive false result locally, while remote evaluation omits globally inactive flags and therefore leaves those keys absent. Exposure events. isEnabled() and getFlag() send a $feature_flag_called event the first time each flag value is read for a user. Experiments use these events as exposures. The client's sendFeatureFlagEvent option sets the default for these reads. Pass { sendFeatureFlagEvents: true } or { sendFeatureFlagEvents: false } to a read to override it, so one snapshot can serve both experiment flags and flags that should send no events. getFlagPayload() never sends events. Trim the request. Pass flagKeys to scope local evaluation, the underlying /flags request, and the returned snapshot to a subset of flags. Remote evaluation responses are not cached, so a key missing both locally and remotely costs one /flags request per evaluateFlags() call. Trim the event payload. Use flags.only([...]) or flags.onlyAccessed() to filter which flags get attached to a captured event without re-fetching.

Parameters

• options? (AllFlagsOptions) - Optional configuration for flag evaluation. Supports the same fields as getAllFlags(). flagKeys scopes local evaluation, the /flags request, and the returned snapshot. onlyEvaluateLocally prevents fallback and leaves unresolved keys absent; the snapshot's unresolvedFlags lists them with a reason.

Returns

• Promise<FeatureFlagEvaluations>

Examples

Basic usage:

const flags = await client.evaluateFlags('user_123', {
  personProperties: { plan: 'enterprise' },
})
if (flags.isEnabled('new-dashboard')) {
  renderNewDashboard()
}
client.capture({ distinctId: 'user_123', event: 'page_viewed', flags })

Scope the  request to specific keys:

const flags = await client.evaluateFlags('user_123', {
  flagKeys: ['new-dashboard', 'checkout-flow'],
  personProperties: { plan: 'enterprise' },
})

Attach only the flags the developer actually checked:

const flags = await client.evaluateFlags('user_123')
if (flags.isEnabled('new-dashboard')) { ... }
client.capture({ distinctId: 'user_123', event: 'page_viewed', flags: flags.onlyAccessed() })

Use  to avoid repeating the distinctId:

await client.withContext({ distinctId: 'user_123' }, async () => {
  const flags = await client.evaluateFlags()
  if (flags.isEnabled('new-dashboard')) { ... }
  client.capture({ event: 'page_viewed', flags })
})

getAllFlags()

Release Tag: public

Get all feature flag values for a specific user.

Parameters

• options? (AllFlagsOptions) - Optional configuration for flag evaluation

Returns

• Promise<Record<string, FeatureFlagValue>>

Examples

Get all flags for a user

// 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' }

With specific flag keys

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

With groups and properties

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

getAllFlagsAndPayloads()

Release Tag: public

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

Parameters

• options? (AllFlagsOptions) - Optional configuration for flag evaluation

Returns

• Promise<PostHogFlagsAndPayloadsResponse>

Examples

Get all flags and payloads for a user

// 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)

With specific flag keys

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

Only evaluate locally

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

getFeatureFlag()

Release Tag: deprecated

Get the value of a feature flag for a specific user. A boolean false is a conclusive off evaluation. undefined means no result is available, for example because the key was not returned or local-only evaluation was inconclusive. Local evaluation resolves cached inactive definitions to false; remote evaluation omits globally inactive flags, so the result depends on which evaluation path is available.

Parameters

• key (string) - The feature flag key

• distinctId (string) - The user's distinct ID

• options? ({ groups?: Record<string, string>; personProperties?: Properties; groupProperties?: Record<string, Properties>; onlyEvaluateLocally?: boolean; sendFeatureFlagEvents?: boolean; disableGeoip?: boolean; }) - Optional configuration for flag evaluation

Returns

Union of:

• Promise<FeatureFlagValue

• undefined>

Examples

Basic feature flag check

// 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 evaluated off, or no value was returned
}

With groups and properties

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

Only evaluate locally

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

getFeatureFlagEvaluationRuntime()

Release Tag: public

Get where a locally loaded feature flag is meant to be evaluated.

Notes:

Read from the definitions local evaluation already holds, so no request is made. A definition that carries no runtime reports all, the default PostHog applies.

Parameters

• key (string) - The feature flag key

Returns

Union of:

• FeatureFlagEvaluationRuntime

• undefined

Examples

const runtime = client.getFeatureFlagEvaluationRuntime('my-flag')
// Returns: 'client'

getFeatureFlagKeysByEvaluationRuntime()

Release Tag: public

Get the keys of locally loaded flags that a runtime can evaluate.

Notes:

A flag set to all suits either runtime, so it is returned for client and for server, and asking for all returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.

Parameters

• evaluationRuntime (FeatureFlagEvaluationRuntime) - The runtime to match

Returns

• string[]

Examples

const clientKeys = client.getFeatureFlagKeysByEvaluationRuntime('client')
// Returns: ['web-banner', 'shared-copy']

getFeatureFlagPayload()

Release Tag: deprecated

Get the payload for a feature flag.

Parameters

• 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?: Properties; groupProperties?: Record<string, Properties>; onlyEvaluateLocally?: boolean; sendFeatureFlagEvents?: boolean; disableGeoip?: boolean; }) - Optional configuration for flag evaluation

Returns

Union of:

• Promise<JsonType

• undefined>

Examples

Get payload for a feature flag

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

Get payload with specific match value

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

With groups and properties

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

getFeatureFlagResult()

Release Tag: 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. A result with enabled: false is a conclusive off evaluation; undefined means no evaluation is available. Local evaluation resolves cached inactive definitions to enabled: false, while remote evaluation omits globally inactive flags.

Parameters

• key (string) - The feature flag key

• options? (FlagEvaluationOptions) - Optional configuration for flag evaluation

Returns

Union of:

• Promise<FeatureFlagResult

• undefined>

Examples

Get flag result

// 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)
}

With groups and properties

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

getRemoteConfigPayload()

Release Tag: public

Get the remote config payload for a feature flag.

Parameters

• flagKey (string) - The feature flag key

Returns

Union of:

• Promise<JsonType

• undefined>

Examples

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

isFeatureEnabled()

Release Tag: deprecated

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

Parameters

• key (string) - The feature flag key

• distinctId (string) - The user's distinct ID

• options? ({ groups?: Record<string, string>; personProperties?: Properties; groupProperties?: Record<string, Properties>; onlyEvaluateLocally?: boolean; sendFeatureFlagEvents?: boolean; disableGeoip?: boolean; }) - Optional configuration for flag evaluation

Returns

Union of:

• Promise<boolean

• undefined>

Examples

Basic feature flag check

// 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 {
  // Flag evaluated off, or no value was returned
  console.log('New feature is not active')
}

With groups and properties

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

isLocalEvaluationReady()

Release Tag: public

Check if local evaluation of feature flags is ready.

Returns

• boolean

Examples

// 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')
}

overrideFeatureFlags()

Release Tag: public

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

Parameters

• overrides (OverrideFeatureFlagsOptions) - Flag overrides configuration

Returns

• void

Examples

// 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 } }
})

reloadFeatureFlags()

Release Tag: public

Reload feature flag definitions from the configured cache provider or PostHog for local evaluation.

Returns

• Promise<void>

Examples

Force reload of feature flags

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

Reload before checking a specific flag

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

waitForLocalEvaluationReady()

Release Tag: public

Wait for local evaluation of feature flags to be ready.

Parameters

• timeoutMs? (number) - Timeout in milliseconds (default: 30000)

Returns

• Promise<boolean>

Examples

Wait for local evaluation

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

Wait with custom timeout

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

Traces methods

getActiveSpan()

Release Tag: public

The span currently active on this async execution path, or null outside any withSpan callback. On the edge build this returns null after an await, because the active span is tracked synchronously there.

Subject to change in a minor release.

Returns

Union of:

• Span

• null

Examples

// Propagate the trace to another service
const traceparent = posthog.getActiveSpan()?.traceparent()
await fetch(url, { headers: traceparent ? { traceparent } : {} })

startSpan()

Release Tag: public

Starts a span without making it active — for work that can't wrap a callback. Prefer withSpan, which ends the span for you. Always returns a handle, so calling code never has to branch: when the traces option is absent, the SDK is disabled, or the user has opted out, the handle is inert and nothing is exported. An inert handle given a parent header still returns it from traceparent(), so a service with tracing off passes a distributed trace through instead of severing it.

Subject to change in a minor release.

Parameters

• name (string)

• options? (StartSpanOptions)

Returns

• Span

Examples

const span = posthog.startSpan('checkout', { attributes: { plan: 'pro' } })
span.setAttribute('cart.items', 3)
span.end()

withSpan()

Release Tag: public

Runs a callback with a span active for its duration and ends the span for you — at return for a sync callback, at settle for an async one. Takes an optional StartSpanOptions between the name and the callback: withSpan(name, fn) or withSpan(name, options, fn). Spans started inside the callback nest under it automatically. If the callback throws or rejects, the span records the exception and the original error is rethrown unchanged. A callback that ends the span itself gets the rethrow but not the recording, since the span is already exported by then. Spans nest across await only on the Node runtime, which tracks the active span with AsyncLocalStorage. The edge build restores the active span when the callback returns its promise, so spans started after an await there begin a new trace.

Subject to change in a minor release.

Parameters

• name (string)

• fn ((span: Span) => T)

Returns

• T

Examples

await posthog.withSpan('POST /checkout', { parent: req.get('traceparent') }, async (span) => {
  span.setAttribute('plan', user.plan)
  return processOrder()
})

Context methods

getContext()

Release Tag: public

Get the current context data.

Returns

Union of:

• ContextData

• undefined

Examples

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

withContext()

Release Tag: 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

• 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)

Returns

• T

Examples

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