Snapshots & Jobs

Snapshots are the versioned artifacts Grounded optimizes. Jobs are the execution units that sync data, mine insights, analyze snapshots, and run optimization or eval flows.

Snapshot Methods

grounded.snapshots.list()
grounded.snapshots.get(snapshotId)
grounded.snapshots.create(input)
grounded.snapshots.fork(snapshotId)
grounded.snapshots.updateDraft(snapshotId, 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)

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)

Fork, Edit, Analyze

This is the core snapshot workflow:

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 backend's analyze-only optimization route. It is useful when you want the system to inspect the current candidate without activating it.

Create A Job Directly

For bigger workflows, call jobs.create() directly.

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

The current backend JobType union is broader than the recommended external surface. For most external usage, stick to:

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

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 exact summary shape depends on the job type. For example, insight-mining jobs return insight counts, severity counts, and referenced sessions.

Source Job And Attribution

You can navigate from a snapshot back to its producing job and attribution results:

const sourceJob = await grounded.snapshots.getSourceJob(fork.id);
const attribution = await grounded.snapshots.getAttribution(fork.id);

Job Loops

Grounded also exposes loop management through the client:

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);

Use loops when you want Grounded itself to orchestrate iterative optimization rounds.

Failure Semantics

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

failed
cancelled

The thrown GroundedApiError includes the job body so you can inspect error, status, and other fields.

Connectors & Sync Tracing