SDK Reference
Connectors & Sync

Connectors & Sync

Connectors let Grounded pull data from external systems into the same session and insight workflows used by direct instrumentation.

Current Connector Model

type ConnectorCategory = 'llm-tracing' | 'session-data';
type ConnectorProvider = 'langsmith' | 'fullstory';

Use them like this:

  • category: 'llm-tracing' with provider: 'langsmith'
  • category: 'session-data' with provider: 'fullstory'

Connector Surface

grounded.connectors.list()
grounded.connectors.get(connectorId)
grounded.connectors.create(input)
grounded.connectors.update(connectorId, input)
grounded.connectors.connect(connectorId, { config? })
grounded.connectors.disconnect(connectorId)
grounded.connectors.sync(connectorId, { from?, to? })
grounded.connectors.delete(connectorId)

Create A LangSmith Connector

const connector = await grounded.connectors.create({
  agentId: 'agt_123',
  name: 'LangSmith prod',
  category: 'llm-tracing',
  provider: 'langsmith',
  config: {
    apiKey: process.env.LANGSMITH_API_KEY!,
    projectName: 'support-prod',
  },
});

Create A FullStory Connector

const connector = await grounded.connectors.create({
  agentId: 'agt_123',
  name: 'FullStory prod',
  category: 'session-data',
  provider: 'fullstory',
  config: {
    apiKey: process.env.FULLSTORY_API_KEY!,
  },
});

Update Without Reconnecting

PATCH /api/connectors/:connectorId exists so the SDK can update connector config without forcing a reconnect flow.

await grounded.connectors.update(connector.id, {
  name: 'LangSmith production',
  config: {
    apiKey: process.env.LANGSMITH_API_KEY!,
    projectName: 'support-prod-v2',
  },
});

Connect

connect() does two things:

  1. marks the connector as connected
  2. enqueues a sync job immediately
const result = await grounded.connectors.connect(connector.id);

Sync Directly

sync() is the historical backfill and reconciliation path.

const syncJob = await grounded.connectors.sync(connector.id, {
  from: '2026-03-01T00:00:00.000Z',
  to: '2026-03-06T00:00:00.000Z',
});
 
await grounded.jobs.wait(syncJob.id);

This is different from direct instrumentation:

  • connectors import provider data into Grounded
  • @grounded/tracing writes Grounded-native traces
  • @grounded/analytics writes Grounded-native telemetry

Mixed Mode

Grounded is designed to let these coexist:

  • import from LangSmith and FullStory
  • emit direct traces and telemetry
  • mirror another provider while keeping Grounded-native data

Connector sync acts as backfill and reconciliation, not as the only source of truth.

Notes

  • list and get operations respect API-key scoping
  • agent-scoped keys can only touch that agent's connectors
  • tenant-scoped keys can list connectors across agents in the same tenant
Client ReferenceSnapshots & Jobs