NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm
npm, #4167 most downloaded on npm
PostHog Node.js integration
Latest stable
5.68.2
Last release 12 days ago
10 Nov 2026
Ships on a steady schedule
a new release about every 9 days
Most releases are documented
notes for 48 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
7 years old
367 releases · first in 2020
Drag across the ruler to compare, or tap a release to open it.
## 5.68.2 ### Patch Changes - #5637 `5fc2aab` Thanks @andehen! - With POSTHOG_CAPTURE_MODE=v1, capture now retries 404 and 429 responses like 408 and
## 5.68.1 ### Patch Changes - #5649 `69b3cb8` Thanks @marandaneto! - Fix empty OR and legacy cohort group matching, and fall back to the server for un
69b3cb8 Thanks @marandaneto! - Fix empty OR and legacy cohort group matching, and fall back to the server for unsupported group types.
(2026-11-10)Your coding agent can read these notes before it upgrades. Set up the MCP server →
## 5.68.0 ### Minor Changes - #5642 `21eb6bb` Thanks @rafaeelaudibert! - feat(node): let the NestJS interceptor take the request's distinct ID from a
21eb6bb Thanks @rafaeelaudibert! - feat(node): let the NestJS interceptor take the request's distinct ID from a getDistinctId option or from identity already set in the PostHog context
(2026-11-10)## 5.67.2 ### Patch Changes - #5648 `f413efc` Thanks @marandaneto! - Fix nested cohort not_in conditions in local feature flag evaluation. (2026-11-10
f413efc Thanks @marandaneto! - Fix nested cohort not_in conditions in local feature flag evaluation.
(2026-11-10)Updated dependencies [`44e6251`]:
44e6251 Thanks @luantaraschi! - Relative date filters in local flag evaluation no longer roll past the end of a shorter month. 1m on March 31 now resolves to February 28, matching the flags service.
(2026-11-10)44e6251]:
feat(core): add PostHogMetrics.flushCoalesced(), a flush that callers can request once per unit of work: concurrent calls share one queued send, and i
#5596 9ffdaf6 Thanks @DanielVisca! - feat(node): add instrumentRequest and posthogHonoMiddleware for fetch-API servers (Hono, Bun, Deno, Next route handlers). They read x-posthog-session-id, wrap the request in withContext, open a server span that continues traceparent and is named by route, mark 5xx as errors, and record http.server.request.duration and http.server.request.count.
feat(core): add PostHogMetrics.flushCoalesced(), a flush that callers can request once per unit of work: concurrent calls share one queued send, and it waits out a metrics backoff. (2026-11-10)
9ffdaf6]:
## 5.66.0 ### Minor Changes - #5633 `12d1f15` Thanks @Silthus! - Convex functions in the default runtime can now import posthog-node without "use node
Updated dependencies [`fee9bee`]:
#5598 fb313fe Thanks @DanielVisca! - feat(node): stamp the configured serviceName (from traces or metrics) on events as service_name
(2026-11-10)
#5599 fee9bee Thanks @DanielVisca! - feat(node): add a logs API, posthog.logger.info(...) and posthog.captureLog(...), configured with the logs option. Records attach the active span's trace and span ids and the withContext distinctId and sessionId, and serviceName defaults to the traces or metrics one.
(2026-11-10)
#5599 fee9bee Thanks @DanielVisca! - feat(node): expose traceId and spanId getters on the Span handle, for correlating logs from other loggers with a trace without parsing traceparent()
(2026-11-10)
fee9bee]:
Updated dependencies [`fac34e4`, `bfbaff7`]:
bfbaff7 Thanks @DanielVisca! - feat(node): expose traceId and spanId getters on the Span handle, for correlating logs from other loggers with a trace without parsing traceparent()
(2026-11-09)## 5.63.2 ### Patch Changes - #5540 `f8e4866` Thanks @andehen! - Treat a /flags response whose flags field is not an object as a failed request instea
Updated dependencies [`28fe8c0`]:
Updated dependencies [`aa66d4c`]:
aa66d4c Thanks @haacked! - metrics.histogram() accepts a bounds option that sets the histogram's bucket boundaries, and beforeSend sees and can change them. The first sample of a histogram (name and unit) fixes its bounds until the client resets. A later sample with different bounds is recorded in the fixed buckets and logs a warning, and a sample with invalid bounds is dropped. The experimental posthog.flags.request.duration histogram now uses the bounds [50, 75, 100, 150, 200, 300, 400, 500, 750, 1000, 1500, 2000, 3000, 5000, 10000] ms, so its p50 and p95 resolve between 50ms and 5s. This changes the metric's buckets, which its experimental status allows.
(2026-11-05)aa66d4c]:
```ts const posthog = new PostHog("phc_...", { secretKey: "phs_..." });
#5509 71c2464 Thanks @Silthus! - posthog.emails.send() can now send email content your code rendered, such as HTML from React Email. Give the email a templateKey and a subject, and pass html, text or both.
const posthog = new PostHog("phc_...", { secretKey: "phs_..." });
const { data, error } = await posthog.emails.send({
to: "user@example.com",
distinctId: "user_123",
templateKey: "password-reset",
subject: "Reset your password",
html: renderedHtml,
});
if (error) throw error;
// 'delivered', 'bounced', ...
const { data: status } = await posthog.emails.get(data.id);
You need a project secret API key, the kind that starts with phs_. Create one under Project secret API keys in your project settings. Set its Transactional email scope to Write to send emails, or to Read for a key that only reads statuses. Pass it to the client as secretKey. Set appHost to your PostHog app URL when you self-host PostHog or send through a reverse proxy.
PostHog records each email's delivery, opens and clicks on the person with that distinctId. It groups every email with the same templateKey, so you see their metrics and logs in one place. The SDK retries a request that hits a network error, a rate limit or an outage twice by default. Every send carries an idempotency key, so a retry never sends the email twice. Pass your own idempotencyKey, such as welcome:user_123, and your job runner's retries are safe too.
A send with your own content also takes from, replyTo and captureEngagement: false. Set migratedFrom on the client to tell PostHog which email provider you moved from. A failed call returns an EmailError with PostHog's code and the HTTP statusCode.
Docs: Send transactional emails with Node.js and the transactional email overview. (2026-11-05)
## 5.61.3 ### Patch Changes - #5532 `88744a9` Thanks @marandaneto! - Skip client-only flag warnings and unnecessary server fallback during bulk evalua
88744a9 Thanks @marandaneto! - Skip client-only flag warnings and unnecessary server fallback during bulk evaluation.
(2026-11-05)## 5.61.2 ### Patch Changes - #5487 `c019e96` Thanks @mayteio! - posthog.emails.send() now sends a flat request body with template_id and distinct_id
## 5.61.1 ### Patch Changes - #5472 `de8435f` Thanks @ablaszkiewicz! - fix: exception autocapture now captures unhandled promise rejections when the a
de8435f Thanks @ablaszkiewicz! - fix: exception autocapture now captures unhandled promise rejections when the app or framework (for example Next.js, Nitro or PM2) has its own unhandledRejection listener, without changing what Node does with the rejection. Each occurrence is captured once per project, however many clients the app creates, and an error reported more than once in the same turn of the event loop (rethrown by a host listener, or one Error object rejected by two promises) is captured once. When the process survives the error, autocapture captures it at the end of the current turn of the event loop, so that a captureException call for the same error in that turn, from the app's own listener or a framework's error hook such as Nitro's, is the one sent, with its distinctId and properties. A captureException call for an error that autocapture already captured in the same turn is skipped. When the app flushes or shuts down a client, that client captures at once what is still waiting for the end of the turn, so a crash handler that flushes or shuts down and then exits still sends the error. A crash is captured whatever the error, an AbortError or a framework's control flow included. A rejection that the app handles only later is still captured, as Node reports it as unhandled. Next.js and React control-flow errors and AbortError rejections are skipped when the process survives them.
(2026-10-30)Updated dependencies [`c705824`]:
c705824 Thanks @mayteio! - Send transactional email from a PostHog email template with posthog.emails.send(), using the new appHost, emailRequestTimeoutMs and emailRequestMaxRetries client options. Read what happened to a sent email with posthog.emails.get(id), using the message ID that send() returned.
(2026-10-30)c705824]:
## 5.60.1 ### Patch Changes - #5471 `0058ef9` Thanks @gustavohstrassburger! - fix: let later conditions resolve a flag locally when an unexpected erro
#5471 0058ef9 Thanks @gustavohstrassburger! - fix: let later conditions resolve a flag locally when an unexpected error follows a filter that local evaluation cannot check, instead of failing the whole flag
(2026-10-29)
#5471 0058ef9 Thanks @gustavohstrassburger! - fix: fall back to the server when a flag depends on a flag that only the server can evaluate (for example, one with a static cohort), instead of letting a later condition choose a different value locally. unresolvedFlags reports such a flag as unresolved_dependency
(2026-10-29)
## 5.60.0 ### Minor Changes - #5270 `4b25f7f` Thanks @DanielVisca! - The Express and NestJS integrations can read the session ID, and the distinct ID
4b25f7f Thanks @DanielVisca! - The Express and NestJS integrations can read the session ID, and the distinct ID of an identified user, from the posthog-js cookie when a request has no tracing headers, so backend events link to browser sessions on same-site requests without frontend configuration. Turn it on with the readPostHogCookie option.
(2026-10-29)Updated dependencies [`503c3ea`]:
503c3ea Thanks @andehen! - Reads from an evaluateFlags() snapshot now honor sendFeatureFlagEvent: false, and isEnabled() / getFlag() accept a sendFeatureFlagEvents option that overrides it for one read. If you set sendFeatureFlagEvent: false and rely on snapshot reads for experiment exposures, pass sendFeatureFlagEvents: true on those reads.
(2026-10-28)503c3ea]:
## 5.58.0 ### Minor Changes - #5314 `096131d` Thanks @pauldambra! - Add an optional OpenTelemetry context processor, and an optional signal that ends
096131d Thanks @pauldambra! - Add an optional OpenTelemetry context processor, and an optional signal that ends a context's lifetime.
(2026-10-28)## 5.57.2 ### Patch Changes - #5422 `b5036c4` Thanks @posthog! - fix: esbuild no longer fails to bundle posthog-node when the optional @opentelemetry/
Updated dependencies [`f827137`]:
#5385 faacff0 Thanks @carlos-marchal-ph! - Apply the client privacyMode option to AI integrations, keep prompts out of errors, provider metadata and OTel spans in privacy mode, and redact MCP tool credentials
(2026-10-23)
#5354 f827137 Thanks @marandaneto! - Fall back instead of returning inconsistent local regex flag results for Unicode and advanced patterns.
(2026-10-23)
Updated dependencies [f827137]:
A condition with a filter local evaluation cannot check and a filter that does not match now resolves locally as no match, instead of falling back to
#5234 1991b99 Thanks @gustavohstrassburger! - feat: report flags local evaluation could not resolve on evaluateFlags() snapshots via unresolvedFlags, tag reads of them with local_evaluation_inconclusive, and warn once about flags whose definition local evaluation does not support
Behavior changes:
$feature_flag_called events from snapshot reads report local_evaluation_inconclusive instead of flag_missing for these flags.strictLocalEvaluation: true. (2026-10-22)1991b99]:
Updated dependencies [`17260e5`]:
17260e5 Thanks @marandaneto! - Fall back from local flag evaluation when a required property value is undefined.
(2026-10-21)17260e5]:
Updated dependencies [`189da75`]:
189da75 Thanks @quotentiroler! - Local flag evaluation now matches a null property with string operators like the flags service, so negated operators such as not_icontains match instead of failing.
(2026-10-21)189da75]:
## 5.56.2 ### Patch Changes - #5263 `cd31356` Thanks @dustinbyrne! - Allow local feature flag evaluation from a shared definition cache without a secr
cd31356 Thanks @dustinbyrne! - Allow local feature flag evaluation from a shared definition cache without a secret or personal API key.
(2026-10-16)## 5.56.1 ### Patch Changes - #5289 `e6598be` Thanks @pauldambra! - Link captured exceptions to active OpenTelemetry traces when the API is available.
e6598be Thanks @pauldambra! - Link captured exceptions to active OpenTelemetry traces when the API is available.
(2026-10-14)Updated dependencies [`7c10169`]:
7c10169 Thanks @DanielVisca! - Attach trace exemplars to metrics recorded inside sampled spans.
(2026-10-13)7c10169]:
Updated dependencies [`8f2d581`]:
8f2d581 Thanks @marandaneto! - Fix before_send callback types to accept non-null events while still allowing null returns to drop events.
(2026-10-12)8f2d581]:
## 5.55.2 ### Patch Changes - #5268 `74d7eb2` Thanks @marandaneto! - Clarify which server-only credentials to use for local evaluation when a project
74d7eb2 Thanks @marandaneto! - Clarify which server-only credentials to use for local evaluation when a project API key is supplied instead.
(2026-10-11)## 5.55.1 ### Patch Changes - #5134 `175413f` Thanks @posthog! - Evict only the least recently used distinct ids from the $feature_flag_called dedupe
5.55.0 Minor Changes #5140 2d2560a Thanks @dustinbyrne ! - Allow featureFlagsPollingInterval: null to disable automatic local flag polling while retai
2d2560a Thanks @dustinbyrne! - Allow featureFlagsPollingInterval: null to disable automatic local flag polling while retaining initialization and manual refresh.5.54.1 Patch Changes #4832 ac479db Thanks @dustinbyrne ! - Support snake_case feature flag cache payloads while preserving compatibility with camelCas
ac479db Thanks @dustinbyrne! - Support snake_case feature flag cache payloads while preserving compatibility with camelCase providers and cached data.5.54.0 Minor Changes #5099 e3955f8 Thanks @marandaneto ! - Expose feature flag evaluation reasons and preserve them in OpenFeature resolution metadata
e3955f8 Thanks @marandaneto! - Expose feature flag evaluation reasons and preserve them in OpenFeature resolution metadata.5.53.0 Minor Changes #5050 31dd1ad Thanks @posthog ! - Read a feature flag's evaluation runtime with getFeatureFlagEvaluationRuntime(key) and getFeatu
Updated dependencies [ f4704ac ]:
f4704ac Thanks @rubychilds! - Honor filters.holdout during local feature flag evaluation. A user in an experiment holdout now receives the holdout-<id> variant instead of being bucketed into a regular variant, matching how the server evaluates the same flag. The holdout is resolved before the release conditions, so a held-out user never reaches the flag's targeting — including when those conditions would have excluded them, so isFeatureEnabled can return true where it previously returned false. Experiments with an active holdout will see variant assignment change for the held-out share of traffic on upgrade, bringing locally evaluated assignments in line with server-evaluated ones.f4704ac]:
Updated dependencies [ 9cd8ebd , aad7464 ]:
#5018 9cd8ebd Thanks @turnipdabeets! - Stop dropping long spans that end: maxSpanAgeMs now evicts spans only once maxLiveSpans is reached, so a span that runs past the age limit and then ends is exported, and its children are no longer orphaned.
(2026-09-21)
#4800 aad7464 Thanks @marandaneto! - Respect the definitions response's property_matching_version during local feature flag evaluation. Version 2 uses explicit boolean/string equality and per-member array matching, while missing or other versions retain service legacy matching (including empty-array truthiness). Preserve the version in Node definition caches and Convex persisted definitions, and propagate it through person, group, cohort and dependency evaluation without mixing snapshots during reloads. Existing numeric ambiguity fallback and SemVer parsing policies are unchanged.
(2026-09-21)
Updated dependencies [9cd8ebd, aad7464]:
Updated dependencies [ 39a8980 ]:
39a8980 Thanks @decknamec! - Server-side feature flags now resolve in posthog-node and posthog-edge even when a proxy rewrites the request's User-Agent. Flags restricted to the client runtime now resolve to undefined in these SDKs, where a rewritten User-Agent previously let them through.39a8980]:
Updated dependencies [ 07c1045 ]:
07c1045 Thanks @marandaneto! - Capture causes and AggregateError members with relationship metadata and individual stacks, limiting output to 50 entries and 1,000 member inspections.07c1045]:
5.52.2 Patch Changes #4951 55c5142 Thanks @marandaneto ! - Fix Express exception events reporting the initial response status instead of the final HTT
55c5142 Thanks @marandaneto! - Fix Express exception events reporting the initial response status instead of the final HTTP status.Updated dependencies [ 4a3c74b ]:
4a3c74b Thanks @turnipdabeets! - Child spans now share their parent's clock, so a child no longer appears to start before or end after its parent by up to a millisecond, or by more when the system clock is adjusted mid-trace.4a3c74b]:
Updated dependencies [ 19e78cc , 19e78cc , 19e78cc , 19e78cc , 19e78cc , 19e78cc , 19e78cc ]:
19e78cc Thanks @turnipdabeets! - Add experimental distributed tracing to posthog-node: startSpan, withSpan and getActiveSpan record spans against a new traces client option. A service with tracing off still forwards an inbound traceparent, including from spans nested inside the one that received it, so a distributed trace is not severed. A traceparent may be passed as the one-element array req.headersDistinct gives. A beforeSpanSend hook sees every span before it is exported and may edit or drop it, and maxAttributesPerSpan, maxEventsPerSpan, maxAttributeValueLength, maxLiveSpans and maxSpanAgeMs bound what a single span and a single process may hold.#4579 19e78cc Thanks @turnipdabeets! - Stop a throwing getter in metrics.resourceAttributes from breaking every metrics export — the key is recorded as [Unserializable] instead.
(2026-09-10)
#4579 19e78cc Thanks @turnipdabeets! - Honor Retry-After when the ingestion endpoint refuses a logs or metrics batch, instead of retrying on the SDK's own schedule alone. A refusal naming a longer wait extends the one being served, up to five minutes from when it started. Retry delays now carry jitter so clients refused together do not return together, and metrics backs off exponentially across consecutive failures rather than retrying on a fixed interval.
(2026-09-10)
#4579 19e78cc Thanks @turnipdabeets! - Logs and metrics now always send service.name and telemetry.sdk.*, even when a resourceAttributes value is too large to encode in full. Previously that value could crowd them out, and the records reached PostHog with no service attribution.
(2026-09-10)
#4579 19e78cc Thanks @turnipdabeets! - Stop sending logs and metrics batches over 10 MiB, or too large to serialize at all, instead of spending a request to discover the endpoint refuses them.
(2026-09-10)
Updated dependencies [19e78cc, 19e78cc, 19e78cc, 19e78cc, 19e78cc, 19e78cc, 19e78cc]:
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Updated dependencies [ 930de19 , d4eee8f ]:
#4639 1faeb74 Thanks @marandaneto! - Handle empty feature flag evaluation key scopes without running local or remote evaluation.
(2026-08-25)
#4610 930de19 Thanks @marandaneto! - Share feature flag matching, hashing, variant, and payload evaluation helpers across the Node.js and Convex SDKs without changing their runtime-specific SemVer behavior.
(2026-08-25)
Updated dependencies [930de19, d4eee8f]:
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Updated dependencies [`0a0206f`]:
0a0206f Thanks @marandaneto! - Normalize capture timestamp overrides to equivalent UTC ISO strings in the browser and Node.js SDKs and shared core.
(2026-08-14)0a0206f]:
Updated dependencies [`c9086de`]:
c9086de Thanks @carlos-marchal-ph! - Public beta captureAi() / captureAiImmediate(): AI events on a dedicated isolated endpoint with the event UUID returned. New enableFullAiCapture option replaces the internal _useAiLane / _enableMultimodalCapture; wrappers route through the AI endpoint and skip redaction/truncation when set (privacy mode still wins).
(2026-08-13)c9086de]:
Updated dependencies [`a77115b`]:
a77115b Thanks @marandaneto! - Log shutdown timeouts without rejecting, and correct the Node.js shutdown() return type to Promise<void>.
(2026-08-12)a77115b]:
Updated dependencies [`64ba193`]:
#4346 4751b33 Thanks @marandaneto! - Enforce configured request timeouts while consuming Capture V1 response bodies.
(2026-08-06)
#4423 64ba193 Thanks @marandaneto! - Use Node's zlib gzip implementation for Node SDK payloads to avoid sustained memory growth from frequent Web Streams compression.
(2026-08-06)
Updated dependencies [64ba193]:
One column per quarter.