Skip to main content
    Ivy Biosciences Docs/Call the platform/API/Sessions API/Session checkpoints

    Session checkpoints

    Time-travel debugging with automatic checkpointing, rollback, and pruning

    sessionscheckpointsrollback

    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, and rolling back is one way to recover if a sync goes wrong.

    Difficulty

    intermediate

    Time

    10 min

    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. Treat a checkpoint as a rollback target within that window, not as an archive.

    Checkpoint Sources

    SourceTrigger
    manualExplicitly requested by the user
    messageAfter an assistant message is finalized
    job_completeAfter a computational job finishes
    subagentAfter a sub-agent completes or fails
    syncAfter a sync operation applies changes
    tool_executionAfter a tool call completes

    Lifecycle

    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). Each checkpoint carries id, threadId, step, source, parentCheckpointId, toolCallId, jobId and createdAt.

    QueryDefaultMeaning
    limit50Page size, capped at 200
    sourcenoneOnly checkpoints from one source in the table above
    curl -s "https://www.ivybiosciences.com/api/v1/sessions/$SESSION_ID/checkpoints?source=job_complete" \
      -H "Authorization: Bearer ivy_your_key" | jq '.checkpoints'

    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). An unknown checkpoint returns 404.

    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"}'

    Pruning

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

    // 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

    CheckpointerEnvironmentUse Case
    MemorySaverTestingEphemeral checkpoints (lost on restart)
    IndexedDBSaverBrowserOffline-first client-side checkpoints
    SupabaseSaverServerPersistent PostgreSQL checkpoint storage

    Server Initialization

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

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

    DevTools

    Browser DevTools are available for checkpoint inspection:

    // 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

    TablePurpose
    harness_checkpointsCheckpoint data with parent links
    harness_sessionsSession state with version tracking
    harness_errorsError tracking for debugging

    Was this page helpful?

    On this page

    On this page

    Loading...