Node.js SDK - Datalyr Docs

Complete reference for @datalyr/api 1.3.1, which posts events to https://ingest.datalyr.com/track from a server.

Requirements

Item	Value
Package	`@datalyr/api`
Current version	`1.3.1`
`engines.node`	`>=14.17.0`
Runtime node version	18 or later
Runtime dependencies	None
Module formats	CommonJS and ESM

Run this SDK on Node 18 or later. It calls global fetch and AbortController, which Node 16 and earlier don’t provide.

Install

npm install @datalyr/api

Initialize

import { Datalyr } from '@datalyr/api'

// Use the object form. The string shorthand carries the key and nothing else.
const datalyr = new Datalyr({ apiKey: process.env.DATALYR_API_KEY })

The constructor throws Error('Datalyr API key is required') on a missing key. This is the only throw in the SDK. A key that does not begin with dk_ logs a warning and continues. The SDK reads no environment variable. Pass the key yourself.

Use the object form when you want failure callbacks. The string shorthand new Datalyr('dk_...') accepts no onError or onDrop.

Authentication

Header	Value
`X-API-Key`	Your write key from Settings → API
`Content-Type`	`application/json`
`User-Agent`	`@datalyr/api/1.3.1`

The SDK sends no workspace ID. The key alone selects the workspace.

Track an event

await datalyr.track({
  event: 'purchase',
  userId: 'user_123',
  anonymousId: 'anon_from_browser', // datalyr.getVisitorId() in the browser
  eventId: 'order_1001',            // your own ID, so a retry can't double-count
  timestamp: new Date(),
  properties: { value: 99.99, currency: 'USD' }
})

timestamp accepts an ISO 8601 string, a Date, epoch seconds, or epoch milliseconds.

Identity

Pass userId, anonymousId, or both on every call. With neither, the SDK mints a fresh anon_<uuid> for that one call. Every such call becomes a separate person with no journey.

Take anonymousId from the browser. Call datalyr.getVisitorId() in the Web SDK and send the value to your server.

What goes on the wire

The SDK posts one event object per request. There is no envelope and no events array.

{
  "userId": "user_123",
  "anonymousId": "anon_9f2c...",
  "eventId": "order_1001",
  "event": "purchase",
  "properties": { "value": 99.99, "currency": "USD", "anonymous_id": "anon_9f2c..." },
  "context": { "library": "@datalyr/api", "version": "1.3.1", "source": "api", "schema_version": 1 },
  "timestamp": "2026-07-25T12:00:00.000Z"
}

Wire field	Value
`userId`	Your ID. camelCase.
`anonymousId`	The browser `visitor_id`. camelCase.
`properties.anonymous_id`	The same value, in snake_case.
`context`	Always the four keys above. A `context` you pass is overwritten.

This SDK sends no distinct_id and no session_id. It has no session concept.

Events the SDK sends for you

Method	Wire event name
`identify()`	`$identify`
`alias()`	`$alias`
`page()`	`$pageview`
`group()`	`$group`
`trackPurchase()`	`purchase`

group() records a plain $group event. Datalyr builds no account or group association from it. Do not use it to model organizations.

Idempotency

Pass the source event ID as eventId for every webhook.

await datalyr.track({
  event: 'invoice_paid',
  userId: customer.id,
  eventId: stripeEvent.id,
  timestamp: stripeEvent.created,
  properties: { value: 49, currency: 'USD' }
})

An eventId over 256 characters is replaced with its first 191 characters, a hyphen, and a SHA-256 hex digest of the original.

Complete method list

Method	Signature
`constructor`	`(config: DatalyrConfig \| string)`
`track`	`(options: TrackOptions) => Promise<void>`
`track` (legacy form)	`(userId: string \| null, event: string, properties?: any) => Promise<void>`
`identify`	`(userId: string, traits?: any, anonymousId?: string) => Promise<void>`
`alias`	`(newUserId: string, previousId?: string, anonymousId?: string) => Promise<void>`
`page`	`(userId: string, name?: string, properties?: any, anonymousId?: string) => Promise<void>`
`group`	`(userId: string, groupId: string, traits?: any, anonymousId?: string) => Promise<void>`
`trackPurchase`	`(userId: string \| null, purchase: PurchaseProperties, opts?: { anonymousId?: string; eventId?: string; timestamp?: string \| Date \| number }) => Promise<void>`
`flush`	`() => Promise<void>`
`close`	`() => Promise<void>`
`getAnonymousId`	`() => string`

PurchaseProperties requires a finite value: number. currency is optional and uppercased.

getAnonymousId() mints a new anon_<uuid> on every call and stores nothing. Never call it to look up an existing person. Read datalyr.getVisitorId() in the browser instead.

Shut down cleanly

await datalyr.flush()   // between invocations of a reused instance
await datalyr.close()   // once, at process shutdown

close() drains the queue within closeTimeout, then stops the timer. After close(), track() logs an error and drops the event with reason closed. flush() returns immediately when the queue is empty. When a drain is already running, it awaits that drain rather than starting a second one.

Configuration

const datalyr = new Datalyr({
  apiKey: process.env.DATALYR_API_KEY,
  flushAt: 20,
  flushInterval: 10_000,
  timeout: 10_000,
  retryLimit: 3,
  maxQueueSize: 1_000,
  closeTimeout: 30_000,
  onError: (event, error) => console.error(event.event, error),
  onDrop: (events, reason) => console.error(reason, events.length)
})

Every numeric option is clamped. A value outside the range becomes the nearest bound.

Option	Type	Default	Unit	Range
`apiKey`	`string`	Required. Throws when missing.	None	None
`host`	`string`	`'https://ingest.datalyr.com/track'`	URL	None
`flushAt`	`number`	`20`	events	1–100
`flushInterval`	`number`	`10000`	milliseconds	1000–3600000
`timeout`	`number`	`10000`	milliseconds	1000–60000
`retryLimit`	`number`	`3`	retries	0–10
`maxQueueSize`	`number`	`1000`	events	100–10000
`closeTimeout`	`number`	`30000`	milliseconds	1000–120000
`debug`	`boolean`	`false`	None	None
`onError`	`(event: TrackEvent, error: Error) => void`	Unset	None	None
`onDrop`	`(events: TrackEvent[], reason: DropReason) => void`	Unset	None	None

host carries its own /track path. An override must include a full path.

Limits

Limit	Value
Auto-flush trigger	20 queued events
HTTP concurrency	10 requests in parallel, one event each
Requests per event	One. The SDK never batches.
Flush interval	10,000 ms
Retries per send	3
Retry backoff	`min(2^n × 1000, 10000)` ms, multiplied by `0.5 + random()/2`
Request timeout	10,000 ms, through `AbortController`
Queue	1000 events. The oldest is dropped first.
Failed flush cycles per event	10, then the event is dropped
Drain passes per flush	12
`close()` budget	30,000 ms
`eventId` length	256 characters

Error behavior

Only the constructor throws. Every other method resolves.

Response	Behavior
`2xx`	Success.
`408`, `429`, any `5xx`	Retried with jittered exponential backoff, up to `retryLimit`.
`401`, `403`	Dropped. Logs an authentication failure once.
Other `4xx`	Dropped immediately. Never retried.
Network, DNS, TLS, abort	Retried like a `5xx`.

An event that survives its retries returns to the front of the queue. After 10 failed flush cycles the SDK drops it.

Drop reasons

onDrop receives one of these six values.

Reason	Cause
`validation_error`	A missing event name, `userId`, `newUserId`, or `groupId`, or a non-finite purchase `value`
`queue_overflow`	The queue reached `maxQueueSize`
`permanent_client_error`	A `4xx` other than `408` or `429`
`max_flush_attempts`	10 failed flush cycles for one event
`close_timeout`	`close()` ran out of time
`closed`	`track()` ran after `close()`

Validation failures log a warning and call onDrop. They never throw.

Serverless functions

export async function handler(req) {
  await datalyr.track({ event: 'webhook_received', userId: req.userId })
  // Flush before the runtime freezes the process, or the event never leaves.
  await datalyr.flush()
}

Call flush() at the end of each invocation. Call close() only when the process exits. A closed instance accepts no more events.

Verify the install

Send one event with a userId you can recognize.
Open Events in Datalyr.
Confirm the event arrives within 30 seconds.

If nothing arrives, add an onDrop callback and log the reason. A permanent_client_error means the API key is wrong. See No events.

​Requirements

​Install

​Initialize

​Authentication

​Track an event

​Identity

​What goes on the wire

​Events the SDK sends for you

​Idempotency

​Complete method list

​Shut down cleanly

​Configuration

​Limits

​Error behavior

​Drop reasons

​Serverless functions

​Verify the install

Requirements

Install

Initialize

Authentication

Track an event

Identity

What goes on the wire

Events the SDK sends for you

Idempotency

Complete method list

Shut down cleanly

Configuration

Limits

Error behavior

Drop reasons

Serverless functions

Verify the install