Get Agent Run Checkpoint Snapshot

Snapshot response

The response contains {checkpoint, snapshot}; snapshot holds the run output at the requested cut.

Checkpoints are derived from the stored transcript. checkpoint_id is a 1-based display identifier; message_index is a transcript cut count used by continue_from. For example, checkpoint "1" can refer to message index 4. Use the returned message boundary, rather than the display identifier, for continuation. Listing or reading a checkpoint does not create a separate durable checkpoint record.

Tool-call/result pairs must remain valid, so an arbitrary requested boundary can move backward. On current main, checkpoint.message_index can retain the requested value even when the snapshot uses an earlier safe cut. For example, requesting index 2 immediately after an unresolved assistant tool call can return only the preceding user message, with snapshot.last_checkpoint_at_message_index=1. Inspect the snapshot's boundary and messages to determine the actual cut. The stored source run remains unchanged.

GET/agents/{agent_id}/runs/{run_id}/checkpoints/{message_index}

Return a derived run snapshot truncated at a message boundary. Use the returned message_index as continue_from when continuing this run.

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Path Parameters

agent_id*Agent Id
run_id*Run Id
message_index*Message Index

Query Parameters

session_id*Session Id

Session ID for the run

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl --request GET 'https://example.com/agents/string/runs/string/checkpoints/0?session_id=string'
null