---
title: Session checkpoints
description: 'Time-travel debugging with automatic checkpointing, rollback, and pruning'
tags:
  - sessions
  - checkpoints
  - rollback
---
Checkpoints let you undo: the sessions API automatically snapshots a session's state at key moments, so you can roll back to any earlier point and replay from there. Reach for them to recover from a bad turn, experiment safely, or debug by stepping backward through a conversation. They snapshot the same sessions you manage in [Manage sessions](/docs/api/sessions-manage), and rolling back is one way to recover if a [sync](/docs/api/sessions-sync) goes wrong.

  intermediate
  10 min
  [Sessions overview](/docs/api/sessions-overview), [Manage sessions](/docs/api/sessions-manage)

## Checkpoints

The runtime saves a snapshot of the session state at each lifecycle event below. Any snapshot can be listed, inspected, or restored.

---

## How Checkpoints Work

Checkpoints are snapshots of `SessionState` taken at specific lifecycle events. Each checkpoint has a parent pointer, forming a linked history chain.

A checkpoint is not rewritten after it is saved, but it is not permanent either: `SupabaseSaver` prunes on its own after each write, keeping the newest 50 per session — see [Pruning](#pruning). Treat a checkpoint as a rollback target within that window, not as an archive.

### Checkpoint Sources

| Source | Trigger |
|--------|---------|
| `manual` | Explicitly requested by the user |
| `message` | After an assistant message is finalized |
| `job_complete` | After a computational job finishes |
| `subagent` | After a sub-agent completes or fails |
| `sync` | After a sync operation applies changes |
| `tool_execution` | After a tool call completes |

### Lifecycle

 cp1["cp_001<br/>(message: user sends 'Predict BRCA1')"]
    cp1 --> cp2["cp_002<br/>(tool_execution: submit_job completes)"]
    cp2 --> cp3["cp_003<br/>(job_complete: esmfold finishes)"]
    cp3 --> cp4["cp_004<br/>(message: assistant analyzes results)"]
    cp3 --> cp5["cp_005<br/>(subagent: literature search completes)"]
    R2["rollback to cp_002 would undo cp_003–cp_005"]
    R1["rollback to cp_001 would undo everything after"]
    R0["rollback to creation would clear all state"]
    cp2 -.-> R2
    cp1 -.-> R1
    S -.-> R0`}
  caption="Checkpoint tree for one session, with the effect of rolling back to each ancestor."
/>

---

## List Checkpoints

`GET /api/v1/sessions/:sessionId/checkpoints` returns `{ checkpoints, total }`, newest first ([reference](/docs/api/reference/get-v1-sessions-sessionid-checkpoints)). Each checkpoint carries `id`, `threadId`, `step`, `source`, `parentCheckpointId`, `toolCallId`, `jobId` and `createdAt`.

| Query | Default | Meaning |
|-------|---------|---------|
| `limit` | `50` | Page size, capped at 200 |
| `source` | none | Only checkpoints from one source in the table above |

**cURL**

```bash
curl -s "https://www.ivybiosciences.com/api/v1/sessions/$SESSION_ID/checkpoints?source=job_complete" \
  -H "Authorization: Bearer ivy_your_key" | jq '.checkpoints'
```

**TypeScript**

```ts
const { checkpoints } = await fetch(`/api/v1/sessions/${sessionId}/checkpoints`, {
  headers: { "Authorization": `Bearer ${apiKey}` },
}).then(r => r.json())

console.log(checkpoints.map((cp) => cp.id))
```

---

## Rollback

Rolling back restores the session to the state captured at a specific checkpoint. All changes made after that checkpoint are discarded.

> Rollback is irreversible — the discarded state is not preserved. Note the current newest checkpoint ID before rolling back if you may want to return to it.

`POST /api/v1/sessions/:sessionId/rollback` takes `{"checkpointId": "..."}` and returns `{ success, sessionId, checkpointId, restoredStep, version, updatedAt }` ([reference](/docs/api/reference/post-v1-sessions-sessionid-rollback)). An unknown checkpoint returns `404`.

**cURL**

```bash
curl -X POST "https://www.ivybiosciences.com/api/v1/sessions/$SESSION_ID/rollback" \
  -H "Authorization: Bearer ivy_your_key" \
  -H "Content-Type: application/json" \
  -d '{"checkpointId": "cp_002"}'
```

**TypeScript**

```ts
await fetch(`/api/v1/sessions/${sessionId}/rollback`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ checkpointId: "cp_002" }),
})
```

---

## Pruning

Pruning removes old checkpoints to save storage. Keep the N most recent with the saver's `prune(sessionId, keepLast)`:

**TypeScript**

```ts
// Keep only the 5 most recent checkpoints
await checkpointer.prune(sessionId, 5)
```

`SupabaseSaver` prunes on its own after each write, keeping the newest 50 per session unless you pass `maxCheckpointsPerSession`.

---

## Storage Backends

| Checkpointer | Environment | Use Case |
|--------------|-------------|----------|
| `MemorySaver` | Testing | Ephemeral checkpoints (lost on restart) |
| `IndexedDBSaver` | Browser | Offline-first client-side checkpoints |
| `SupabaseSaver` | Server | Persistent PostgreSQL checkpoint storage |

### Server Initialization

The server-side execute endpoint initializes the runtime with a `SupabaseSaver`:

```ts
const runtime = new SessionRuntime({
  storage: new SupabaseAdapter({ client: serviceRoleClient }),
  checkpointer: new SupabaseSaver({ client: serviceRoleClient }),
})
```

---

## DevTools

Browser DevTools are available for checkpoint inspection:

```js
// In browser console
__HARNESS_DEVTOOLS__.checkpoints()    // List all checkpoints
__HARNESS_DEVTOOLS__.rollback("cp_x") // Roll back to a checkpoint
__HARNESS_DEVTOOLS__.session          // Current session state
__HARNESS_DEVTOOLS__.tools()          // List available tools
```

> DevTools are only available when the session React hooks are mounted. Import `useHarnessDevTools` to enable them.

---

## Database Tables

| Table | Purpose |
|-------|---------|
| `harness_checkpoints` | Checkpoint data with parent links |
| `harness_sessions` | Session state with version tracking |
| `harness_errors` | Error tracking for debugging |

## Read next

- [Manage sessions](/docs/api/sessions-manage) — session management
- [Message execution](/docs/api/sessions-execute) — streaming triggers checkpoints
- [Sync protocol](/docs/api/sessions-sync) — sync creates checkpoints
