> ## Documentation Index > Fetch the complete documentation index at: https://docs.veri.studio/llms.txt > Use this file to discover all available pages before exploring further. # Roll a session back to a checkpoint > Discards the sandbox's current filesystem and conversation position and restarts it from the checkpoint, in place: same session id, same key, same transcript (the rollback is recorded as an event; earlier events stay readable). Allowed while `ready` or `paused` (409 while a run is in progress or an approval is pending); the session is `provisioning` until the runtime reports `ready`. Running processes do not survive. Rolling back refreshes the checkpoint's 30-day expiry. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/sessions/{session_id}/rollback openapi: 3.1.0 info: title: Veri API description: >- REST API for the Veri RL post-training platform. All requests require a Bearer API key (`vk_` prefix). license: name: '' version: 0.1.0 servers: - url: https://api.veri.studio description: Production security: [] tags: - name: Training jobs description: Create, monitor, and manage training jobs. - name: Datasets description: Upload and connect training datasets. - name: Deployments description: Serve trained models and run inference. - name: Volumes description: Persistent file storage mounted into jobs. - name: Models description: Custom model registry deployments serve from. - name: Regions description: Discover available launch regions. - name: GPU description: Live GPU availability by provider and region. - name: Code artifacts description: Upload custom training script bundles. - name: Billing description: Credit balance and transaction history. - name: API keys description: Create and revoke API keys. - name: Account description: The authenticated caller's identity. - name: Settings description: Account-level integrations (Weights & Biases). - name: Metrics description: Prometheus metrics export for your own observability stack. - name: Evaluators description: 'Evaluators: versioned scoring rules (LLM judge, code, human).' - name: Experiments description: >- Experiments: offline runs of a pinned dataset snapshot through a target, scored by pinned evaluators. - name: Annotation queues description: >- Human review: queue traces, threads and experiment items, reserve one at a time, score them and feed corrections back into datasets. - name: Monitors description: >- Monitors: evaluators scoring a sampled share of a deployment's live traffic. - name: Observability description: Agent conversations, agents and their traffic. - name: Public runs description: Unauthenticated reads of runs their owners published to Explore. paths: /v1/sessions/{session_id}/rollback: post: tags: - Sessions summary: Roll a session back to a checkpoint description: >- Discards the sandbox's current filesystem and conversation position and restarts it from the checkpoint, in place: same session id, same key, same transcript (the rollback is recorded as an event; earlier events stay readable). Allowed while `ready` or `paused` (409 while a run is in progress or an approval is pending); the session is `provisioning` until the runtime reports `ready`. Running processes do not survive. Rolling back refreshes the checkpoint's 30-day expiry. operationId: rollback parameters: - name: session_id in: path description: Session ID required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/SessionRollbackRequest' required: true responses: '200': description: The session, provisioning again until the runtime reports ready content: application/json: schema: $ref: '#/components/schemas/SessionResponse' '404': description: Session or checkpoint not found in this workspace '409': description: Not ready or paused '501': description: The sandbox runtime does not support rollback security: - bearerAuth: [] components: schemas: SessionRollbackRequest: type: object required: - checkpoint_id properties: checkpoint_id: type: string SessionResponse: type: object required: - object - id - environment_id - environment_version - harness - status - awake_seconds - total_cost_usd - rate_usd_per_hour - egress_bytes - egress_usd_per_gb - tool_calls - tool_call_usd_per_1k - created_by - created_at - updated_at properties: object: type: string id: type: string environment_id: type: string environment_version: type: integer format: int32 harness: type: string description: |- The agent harness the session runs (`claude-code`), from its pinned environment version. status: type: string description: >- provisioning | ready | running | awaiting_approval | paused | ended | failed title: type: - string - 'null' budget_usd: type: - number - 'null' format: double awake_seconds: type: integer format: int64 description: Seconds the sandbox has been awake (what the session meter bills). total_cost_usd: type: number format: double description: Charged so far (USD). rate_usd_per_hour: type: number format: double description: >- Price per awake hour (USD) this session bills at, fixed at create from the environment's `size`. egress_bytes: type: integer format: int64 description: |- Request + response bytes through the sandbox's egress interceptor (every mode; in `unrestricted` only the intercepted hosts). egress_usd_per_gb: type: number format: double description: |- Price per GB of `egress_bytes` (USD), fixed at create: non-zero only for an `audited_open` environment. tool_calls: type: integer format: int64 description: |- Billable third-party tool executions (Composio): each app tool run through `COMPOSIO_MULTI_EXECUTE_TOOL` counts one; search, schema and connection tools are free. tool_call_usd_per_1k: type: number format: double description: >- Price per 1,000 `tool_calls` (USD), fixed at create: non-zero only when the environment has Composio tools. The workspace's monthly free allowance is applied when the calls are settled. started_at: type: - string - 'null' format: date-time last_active_at: type: - string - 'null' format: date-time paused_at: type: - string - 'null' format: date-time ended_at: type: - string - 'null' format: date-time failure_code: type: - string - 'null' error_message: type: - string - 'null' created_by: type: string created_at: type: string format: date-time updated_at: type: string format: date-time parent_session_id: type: - string - 'null' description: 'Set on a forked child: the session it was forked from.' forked_from_checkpoint_id: type: - string - 'null' description: 'Set on a forked child: the parent''s checkpoint it started from.' usage: oneOf: - type: 'null' - $ref: '#/components/schemas/SessionUsageSummary' description: >- Lifecycle timings, runs, model calls, tokens and model cost derived from the transcript. Only on `GET /v1/sessions/{id}`; absent on the list. resources: oneOf: - type: 'null' - $ref: '#/components/schemas/SessionResources' description: >- The newest sandbox resource sample (CPU load, memory, disk) from the runtime's heartbeat; absent until the first one. SessionUsageSummary: type: object description: |- What `GET /v1/sessions/{id}` reports as `usage`: lifecycle timings, run counts, model tokens and cost, all derived from `session_events` in one pass. Never stored; the transcript is the source of truth. required: - runs - run_duration_ms - interrupts - pauses - llm_calls - tokens - permission_denials - approvals - tool_calls properties: boot_ms: type: - integer - 'null' format: int64 description: |- Create -> first `ready`: the runtime's own `boot_ms` when it stamped one, else the control plane's created_at -> ready clock. restore_ms: type: - integer - 'null' format: int64 description: The latest resume's restore time (snapshot -> ready). snapshot_ms: type: - integer - 'null' format: int64 description: The latest pause's snapshot time. runs: type: integer format: int64 description: >- `run.completed` events (turns the agent finished, interrupted or not). run_duration_ms: $ref: '#/components/schemas/RunDurationMs' interrupts: type: integer format: int64 description: >- `session.interrupted` events plus runs that ended by `user.interrupt`. pauses: type: integer format: int64 description: Times the session went `paused` (user, idle or budget). llm_calls: type: integer format: int64 description: >- Model calls: per-call `usage` rows from the egress tee when present, else the harness's per-message (OpenCode: per-step) `usage` rows. 0 when the harness reports usage only per turn or per run (Codex): those rows do not say how many model calls a turn made. tokens: $ref: '#/components/schemas/SessionTokens' model_cost_usd: type: - number - 'null' format: double description: >- Model spend. `null` when the session's environment version uses a Veri deployment: those calls bill through the deployment (GPU time), and the harness's figure is an Anthropic list-price guess keyed by its own model alias, wrong for that model (VS-498). For an external endpoint, the harness estimate (same as `harness_estimated_cost_usd`). Never what Veri bills: that is `total_cost_usd` on the session. harness_estimated_cost_usd: type: - number - 'null' format: double description: >- Claude Code's own cost estimate (`total_cost_usd`, else the sum of `model_usage[*].cost_usd`) for an external endpoint; `null` for a Veri deployment. The harness reports a running total per process, so this is the last figure of each harness process, summed. permission_denials: type: integer format: int64 description: Tool calls the harness refused for lack of permission. approvals: $ref: '#/components/schemas/SessionApprovals' tool_calls: type: integer format: int64 description: |- Billable third-party tool executions (Composio): the session's `tool_calls`. SessionResources: type: object description: |- The sandbox resource sample a heartbeat carries (every field optional: the runtime omits what it could not read), plus when it was taken. required: - sampled_at properties: load1: type: - number - 'null' format: double description: 1-minute load average (`/proc/loadavg`). mem_bytes: type: - integer - 'null' format: int64 description: cgroup v2 `memory.current`. mem_limit_bytes: type: - integer - 'null' format: int64 description: cgroup v2 `memory.max`; absent when unlimited. disk_bytes: type: - integer - 'null' format: int64 description: Bytes used on the filesystem holding /workspace. sampled_at: type: string format: date-time RunDurationMs: type: object description: Run wall time over the session's `run.completed` events, ms. properties: p50: type: - integer - 'null' format: int64 max: type: - integer - 'null' format: int64 SessionTokens: type: object description: |- Token totals of one session. `input`, `cache_read` and `cache_creation` come from the most specific `usage` scope the session has, and only that one, so a token reported per call and again in a roll-up counts once: the per-call rows from the egress tee (`usage{scope:"call"}`), else the harness's per-message rows (`scope:"message"`: Claude Code, LangGraph, CrewAI), per-step rows (`scope:"step"`: OpenCode), per-turn rows (`scope:"turn"`: Codex), else the per-run roll-up (`scope:"run"`). `output` comes from the per-run roll-up, because Claude Code's per-message output count is its message_start placeholder. required: - input - output - cache_read - cache_creation properties: input: type: integer format: int64 output: type: integer format: int64 cache_read: type: integer format: int64 cache_creation: type: integer format: int64 SessionApprovals: type: object description: |- Human approvals (`agent.approval_request` / `user.approval`, O6). All zero while the environment has no `ask` rules. required: - requested - approved - denied - wait_ms_total properties: requested: type: integer format: int64 approved: type: integer format: int64 denied: type: integer format: int64 wait_ms_total: type: integer format: int64 description: Sum over answered requests of (answer time - request time), ms. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: API key with the `vk_` prefix. Create one from the dashboard. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.