Snapshots & Jobs

Snapshots are the versioned artifacts Grounded improves. Jobs are the async execution units that sync data, mine insights, analyze snapshots, optimize candidates, and run eval workflows.

Snapshot Methods

grounded.snapshots.list()
grounded.snapshots.get(snapshotId)
grounded.snapshots.create(input)
grounded.snapshots.createDraft(agentId, seed?)
grounded.snapshots.fork(snapshotId)
grounded.snapshots.updateDraft(snapshotId, input)
grounded.snapshots.commitDraft(snapshotId, message, input?)
grounded.snapshots.runAnalysis(snapshotId)
grounded.snapshots.activate(snapshotId)
grounded.snapshots.reject(snapshotId)
grounded.snapshots.delete(snapshotId)
grounded.snapshots.getSourceJob(snapshotId)
grounded.snapshots.getAttribution(snapshotId)
grounded.snapshots.getAttributionEvidence(snapshotId, params?)

Job Methods

grounded.jobs.list()
grounded.jobs.get(jobId)
grounded.jobs.create(input)
grounded.jobs.cancel(jobId)
grounded.jobs.steps(jobId)
grounded.jobs.summary(jobId)
grounded.jobs.wait(jobId, options)

Create A Draft

const draft = await grounded.snapshots.createDraft('agt_123', {
  parentSnapshotId: 'snap_base_123',
  systemPrompt: 'Tighten refund policy handling and cite policy names.',
});

This is a client helper over snapshots.create(). It keeps the common draft defaults in one place.

Commit A Draft

await grounded.snapshots.commitDraft(
  draft.id,
  'Refine refund handling',
  {
    systemPrompt: 'Tighten refund policy handling and ask one clarifying question before escalating.',
  },
);

This is a helper over snapshots.updateDraft().

Fork, Edit, Analyze

const fork = await grounded.snapshots.fork('snap_base_123');
 
await grounded.snapshots.updateDraft(fork.id, {
  systemPrompt: 'Tighten refund policy handling and cite policy names.',
  commitMessage: 'Refine refund handling',
});
 
const analysisJob = await grounded.snapshots.runAnalysis(fork.id);
await grounded.jobs.wait(analysisJob.id);

runAnalysis() maps to the analyze-only route. It is useful when you want inspection without activation.

Create Jobs Directly

For bigger workflows, call jobs.create() directly with one of the supported job kinds:

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

const job = await grounded.jobs.create({
  agentId: 'agt_123',
  type: 'optimize-snapshot',
  snapshotId: fork.id,
  effort: 'medium',
  topK: 3,
});
 
await grounded.jobs.wait(job.id);

Wait, Steps, And Summary

Poll For Completion

const completed = await grounded.jobs.wait(job.id, {
  pollIntervalMs: 1_500,
  timeoutMs: 15 * 60_000,
});

Inspect Execution Steps

const steps = await grounded.jobs.steps(job.id);

Read Summarized Output

const summary = await grounded.jobs.summary(job.id);

The summary shape depends on the job type. Eval and rubric-eval jobs now return meaningful summary payloads instead of a generic empty shell.

Failure Semantics

jobs.wait() throws GroundedJobError when a job lands in:

failed
cancelled

The error still carries the job body so you can inspect status, error, and related fields.

Source Job And Attribution

const sourceJob = await grounded.snapshots.getSourceJob(fork.id);
const attribution = await grounded.snapshots.getAttribution(fork.id);
const evidence = await grounded.snapshots.getAttributionEvidence(fork.id, {
  limit: 20,
});

Use attribution evidence when you need the concrete rows behind the summary.

Job Loops

Grounded also exposes loop management:

const loop = await grounded.jobLoops.create({
  agentId: 'agt_123',
  totalRounds: 3,
  effort: 'medium',
});
 
await grounded.jobLoops.pause(loop.id);
await grounded.jobLoops.resume(loop.id, 'retry');
await grounded.jobLoops.cancel(loop.id);

Connectors & Sync Tracing