Client Reference

@grounded/client exposes one top-level class:

import { Grounded } from '@grounded/client';

Constructor

const grounded = new Grounded({
  apiKey,
  baseUrl,
  timeoutMs,
  maxRetries,
  fetch,
});

Shared Return Shapes

List methods return:

type ListResponse<T> = {
  data: T[];
  page?: number;
  pageSize?: number;
  total?: number;
  totalPages?: number;
  hasMore?: boolean;
};

Error Types

Most HTTP failures throw GroundedApiError:

class GroundedApiError extends Error {
  status: number;
  requestId?: string;
  code?: string;
  details?: unknown;
  body?: unknown;
}

Terminal failed or cancelled jobs throw GroundedJobError:

class GroundedJobError extends GroundedApiError {
  job: Job;
  reason: 'failed' | 'cancelled';
}

Agents

Method	Description
`agents.list({ tenantId? })`	list agents
`agents.get(agentId)`	fetch one agent
`agents.create({ name, tenantId? })`	create a new agent

Connectors

Method	Description
`connectors.list({ agentId? })`	list connectors
`connectors.get(connectorId)`	fetch one connector
`connectors.create(input)`	create a connector
`connectors.update(connectorId, input)`	patch connector metadata or config
`connectors.delete(connectorId)`	delete a connector
`connectors.connect(connectorId, { config? })`	mark connected and trigger sync
`connectors.disconnect(connectorId)`	mark disconnected
`connectors.sync(connectorId, { from?, to? })`	enqueue a sync job directly

Connector creation is provider-aware:

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',
  },
});

Current connector categories:

'llm-tracing'
'session-data'

Current providers:

'langsmith'
'fullstory'

Traces

Method	Description
`traces.list(params?)`	list stored trace records
`traces.get(traceId)`	fetch one trace
`traces.listSpans(traceId)`	list spans for one trace
`traces.listScores(traceId)`	list scores for one trace

const traces = await grounded.traces.list({
  agentId: 'agt_123',
  sessionId: 'chat_123',
});
 
const spans = await grounded.traces.listSpans(traces.data[0]!.id);
const scores = await grounded.traces.listScores(traces.data[0]!.id);

Sessions

Method	Description
`sessions.list(params?)`	list derived sessions
`sessions.get(sessionId)`	fetch one session
`sessions.stats(agentId)`	fetch aggregate session stats

The public SDK keeps sessions read-focused. You write traces and telemetry, and Grounded derives sessions from that data.

await grounded.sessions.list({
  agentId: 'agt_123',
  outcome: 'resolved',
  page: 1,
  pageSize: 20,
  q: 'refund',
});

Insights

Method	Description
`insights.list({ agentId?, ids? })`	list insights
`insights.get(insightId)`	fetch one insight

Snapshots

Method	Description
`snapshots.list(params?)`	list snapshots
`snapshots.get(snapshotId)`	fetch one snapshot
`snapshots.create(input)`	create a snapshot
`snapshots.createDraft(agentId, seed?)`	create a candidate draft helper
`snapshots.fork(snapshotId)`	create a candidate copy
`snapshots.updateDraft(snapshotId, input)`	patch draft content
`snapshots.commitDraft(snapshotId, message, input?)`	helper over `updateDraft()`
`snapshots.runAnalysis(snapshotId)`	enqueue analyze-only optimization
`snapshots.activate(snapshotId)`	mark active
`snapshots.reject(snapshotId)`	mark rejected
`snapshots.delete(snapshotId)`	delete snapshot
`snapshots.getSourceJob(snapshotId)`	resolve producing job
`snapshots.getAttribution(snapshotId)`	fetch attribution summary
`snapshots.getAttributionEvidence(snapshotId, params?)`	fetch attribution evidence rows

Jobs

Method	Description
`jobs.list(params?)`	list jobs
`jobs.get(jobId)`	fetch one job
`jobs.create(input)`	create a typed job
`jobs.cancel(jobId)`	cancel a job
`jobs.steps(jobId)`	fetch ordered execution steps
`jobs.summary(jobId)`	fetch summarized output
`jobs.wait(jobId, options?)`	poll until terminal state

Supported public job kinds:

sync
session-hydration
insight-mining
optimize-snapshot
run-eval
run-rubric-eval

Example:

const job = await grounded.jobs.create({
  agentId: 'agt_123',
  type: 'optimize-snapshot',
  snapshotId: 'snap_live',
  effort: 'medium',
  topK: 3,
});
 
await grounded.jobs.wait(job.id, {
  timeoutMs: 20 * 60_000,
});
 
const summary = await grounded.jobs.summary(job.id);

Job Loops

Method	Description
`jobLoops.list({ agentId?, status? })`	list loops
`jobLoops.get(loopId)`	fetch loop detail
`jobLoops.create(input)`	create and start a loop
`jobLoops.pause(loopId)`	pause a running loop
`jobLoops.resume(loopId, action?)`	resume with `retry` or `skip`
`jobLoops.cancel(loopId)`	cancel a loop

Evals

Method	Description
`evals.list({ agentId? })`	list eval definitions
`evals.create(input)`	create an eval definition
`evals.run(evalId, snapshotId)`	run an eval against a snapshot
`evals.listRuns(params?)`	list historical eval runs

Datasets

Method	Description
`datasets.list({ agentId? })`	list datasets
`datasets.get(datasetId)`	fetch one dataset
`datasets.create(input)`	create a dataset and rows
`datasets.listRows(datasetId)`	list rows in a dataset

Analytics Connectors & Sync