@vanta-dev/node

Node.js SDK for the Vanta event tracking platform. Track events, record metrics, manage uptime monitors, and query analytics from server-side code.

Installation

npm install @vanta-dev/node

Getting started

import { Vanta } from '@vanta-dev/node'

const vanta = new Vanta({
  apiKey: 'vk_your_api_key',
})

await vanta.track({ event: 'purchase', data: { amount: 49.99 } })
await vanta.shutdown()

The SDK works with both ES modules and CommonJS. In a CommonJS project use require:

const { Vanta } = require('@vanta-dev/node')

const vanta = new Vanta({ apiKey: 'vk_your_api_key' })

Configuration

const vanta = new Vanta({
  apiKey: 'vk_...',           // required
  apiUrl: 'https://vantapi.pancake.wtf',  // defaults to http://localhost:3001
  source: 'my-server',        // source identifier for events
  flushInterval: 10000,       // ms between automatic flushes (default: 10000)
  flushSize: 20,              // queue size that triggers an immediate flush (default: 20)
  maxRetries: 3,              // transport retries on failure (default: 3)
  batchSize: 100,             // max events per batch request (default: 100)
})

Tracking events

await vanta.track({
  event: 'signup',
  userId: 'user_123',
  data: { plan: 'pro' },
  tags: { region: 'us-east' },
})

Event names cannot start with $, which is reserved for internal Vanta events.

Identifying users

await vanta.identify({
  userId: 'user_123',
  email: '[email protected]',
  name: 'Jane',
})

Groups

await vanta.group({
  groupId: 'org_456',
  type: 'organization',
  name: 'Acme Corp',
})

Metrics

Measurements record observations; counters accumulate changes:

await vanta.measure({ name: 'response_time', value: 142, unit: 'ms' })

await vanta.increment('page_view')
await vanta.increment('items_processed', 25)
await vanta.decrement('queue_depth', 3)

await vanta.metrics.submit([
  { type: 'measurement', name: 'cpu_usage', value: 67.2, unit: 'percent' },
  { type: 'increment', name: 'page_view' },
])

const result = await vanta.metrics.query({
  name: 'response_time',
  time: { start: '2026-08-14T00:00:00Z', end: '2026-08-21T00:00:00Z' },
  aggregation: 'p95',
})

const series = await vanta.metrics.timeseries({
  name: 'page_view',
  interval: '1d',
})

const current = await vanta.metrics.current({ name: 'queue_depth' })

const names = await vanta.metrics.list()

Counter queries return the net change (sum of increments minus decrements). Omitting time queries all recorded history.

Uptime monitoring

Monitors are created, edited, and deleted from the Vanta dashboard. Use the SDK to send heartbeats, read monitors, and start or stop the local heartbeat loop.

await vanta.uptime.heartbeat('api-health')

const monitors = await vanta.uptime.listMonitors()
const stats = await vanta.uptime.getStats('mon_123', '30d')

const handle = vanta.uptime.start('api-health', { intervalMs: 30000 })
handle.stop()

Querying events and analytics

import { filter, and, timeRange } from '@vanta-dev/node'

const events = await vanta.queryEvents({
  filters: and(
    filter('type', 'equals', 'purchase'),
    filter('data.amount', 'gt', 50),
  ),
  time: timeRange('2025-01-01T00:00:00Z', '2025-02-01T00:00:00Z'),
})

const count = await vanta.count({
  filters: filter('type', 'equals', 'signup'),
  time: timeRange('2025-01-01T00:00:00Z', '2025-02-01T00:00:00Z'),
})

const grouped = await vanta.groupBy({
  groupBy: ['data.plan'],
  time: timeRange('2025-01-01T00:00:00Z', '2025-02-01T00:00:00Z'),
})

const trend = await vanta.timeseries({
  interval: 'day',
  time: timeRange('2025-01-01T00:00:00Z', '2025-02-01T00:00:00Z'),
})

Error handling

The SDK exports several error classes for programmatic handling:

import { VantaError, AuthenticationError, RateLimitError, NetworkError } from '@vanta-dev/node'

try {
  const result = await vanta.metrics.query({ name: 'response_time' })
} catch (err) {
  if (err instanceof AuthenticationError) {
    // invalid API key
  } else if (err instanceof RateLimitError) {
    // retry after err.retryAfter seconds
  } else if (err instanceof NetworkError) {
    // connectivity issue
  }
}

Queued calls such as track(), measure(), and increment() are delivered in the background. Failed batches are re-queued and reported through the onDeliveryError callback instead of throwing.

Graceful shutdown

Call shutdown() before your process exits to flush any queued events:

process.on('SIGTERM', async () => {
  await vanta.shutdown()
  process.exit(0)
})

Documentation

Read the full Node.js SDK documentation at vanta.pancake.wtf.