SDK Reference
Initialization

Initialization

You initialize the three Grounded SDKs independently because they serve different runtimes and different jobs.

@grounded/client

import { Grounded } from '@grounded/client';
 
const grounded = new Grounded({
  apiKey: process.env.GROUNDED_SECRET_KEY!,
  baseUrl: process.env.GROUNDED_BASE_URL ?? 'http://localhost:3001',
  timeoutMs: 30_000,
  maxRetries: 2,
});

Options

OptionRequiredDefaultMeaning
apiKeyyesnonesecret API key
baseUrlnohttp://localhost:3001Grounded origin or origin plus /api
timeoutMsno30000per-request timeout
maxRetriesno2retries for 429 and 5xx responses
fetchnoglobal fetchcustom fetch implementation

@grounded/tracing

import { GroundedTracing } from '@grounded/tracing';
 
const tracing = new GroundedTracing({
  publishableKey: process.env.GROUNDED_PUBLISHABLE_KEY!,
  agentId: 'agt_123',
  baseUrl: process.env.GROUNDED_BASE_URL ?? 'http://localhost:3001',
  environment: 'production',
  release: 'api-2026-03-09',
  flushAt: 20,
  flushIntervalMs: 5_000,
  sampleRate: 1,
  timeoutMs: 15_000,
  maxRetries: 2,
});

Options

OptionRequiredDefaultMeaning
publishableKey or apiKeyyesnonepublishable tracing key
agentIdnononedefault agent for all traces
baseUrlnohttp://localhost:3001Grounded origin or origin plus /api
environmentnononeattached to trace.resource.environment
releasenononeattached to trace.resource.release
flushAtno20flush after this many completed traces are queued
flushIntervalMsno5000background flush cadence
sampleRateno1fraction of traces to keep
timeoutMsno15000per-flush timeout
maxRetriesno2retries for 429, 5xx, and retryable network errors
fetchnoglobal fetchcustom fetch implementation
masknononetransform a trace before it is sent

@grounded/analytics

import { init } from '@grounded/analytics';
 
const analytics = init({
  publishableKey: process.env.NEXT_PUBLIC_GROUNDED_PUBLISHABLE_KEY!,
  agentId: 'agt_123',
  baseUrl: process.env.NEXT_PUBLIC_GROUNDED_BASE_URL ?? 'http://localhost:3001',
  flushAt: 20,
  flushIntervalMs: 5_000,
  capturePageViews: true,
  mirror: { fullstory: window.FS },
});

Options

OptionRequiredDefaultMeaning
publishableKey or apiKeyyesnonepublishable telemetry key
agentIdyesnonetarget agent for telemetry
baseUrlnohttp://localhost:3001Grounded origin or origin plus /api
flushAtno20flush after this many queued events
flushIntervalMsno5000background flush cadence
timeoutMsno15000per-flush timeout
maxRetriesno2retries for 429, 5xx, and retryable network errors
fetchnoglobal fetchcustom fetch implementation
storagenolocalStorage or memory fallbackpersistence for sessionId, anonymousId, userId
capturePageViewsnofalsecall page() on init
mirror.fullstorynononeforward identify and track calls to FullStory

Base URL Normalization

All SDK requests target the existing /api routes.

These inputs are equivalent:

baseUrl: 'http://localhost:3001'
baseUrl: 'http://localhost:3001/api'

Initialization Patterns

Long-Running API Server

const grounded = new Grounded({
  apiKey: process.env.GROUNDED_SECRET_KEY!,
});
 
const tracing = new GroundedTracing({
  publishableKey: process.env.GROUNDED_PUBLISHABLE_KEY!,
  agentId: 'agt_123',
  environment: process.env.NODE_ENV,
  release: process.env.GIT_SHA,
});

Browser App

const analytics = init({
  publishableKey: process.env.NEXT_PUBLIC_GROUNDED_PUBLISHABLE_KEY!,
  agentId: 'agt_123',
  capturePageViews: true,
});

Worker Or Batch Script

const tracing = new GroundedTracing({
  publishableKey: process.env.GROUNDED_PUBLISHABLE_KEY!,
  agentId: 'agt_123',
  flushIntervalMs: 0,
});
 
try {
  await runBatch();
} finally {
  await tracing.shutdown();
}

What Happens Under The Hood

Grounded

  • adds Authorization: Bearer ...
  • adds Idempotency-Key on POST
  • retries 429 and 5xx
  • normalizes list route shapes

GroundedTracing

  • validates that each trace can join Grounded's session model
  • batches completed traces
  • applies sampling before enqueue
  • injects environment and release
  • sends to /api/traces/batch

GroundedAnalytics

  • persists sessionId and anonymousId
  • batches browser events
  • sends to /api/telemetry/batch
  • returns correlation context through getContext()

Next

AuthenticationAnalytics