> ## 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. # Fork a session > Starts `count` new sessions from a checkpoint of this one. Each child gets the checkpoint's files and conversation (the agent continues from that point in its own, new conversation), the parent's environment version and rate, its own model access key and its own budget. Children are ordinary sessions: billed, capped and ended individually. Without `checkpoint_id` a fresh checkpoint is taken first. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/sessions/{session_id}/fork 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}/fork: post: tags: - Sessions summary: Fork a session description: >- Starts `count` new sessions from a checkpoint of this one. Each child gets the checkpoint's files and conversation (the agent continues from that point in its own, new conversation), the parent's environment version and rate, its own model access key and its own budget. Children are ordinary sessions: billed, capped and ended individually. Without `checkpoint_id` a fresh checkpoint is taken first. operationId: fork parameters: - name: session_id in: path description: Session ID required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/SessionForkRequest' required: true responses: '201': description: The checkpoint used and the children content: application/json: schema: $ref: '#/components/schemas/SessionForkResponse' '400': description: count outside 1..=4, invalid budget, or managed agents disabled '404': description: Session or checkpoint not found in this workspace '409': description: >- A fresh checkpoint was needed but the session is not ready or paused, or the session's harness cannot fork (`harness_does_not_support_fork`) '429': description: The children would exceed the workspace's concurrent-session cap '501': description: No sandbox backend configured, or it does not support checkpoints security: - bearerAuth: [] components: schemas: SessionForkRequest: type: object properties: checkpoint_id: type: - string - 'null' description: >- Checkpoint to fork from (default: take a fresh checkpoint first, which needs the session `ready` or `paused`). count: type: - integer - 'null' format: int32 description: |- Children to start, 1..=4 (default 1). Every child needs a free slot under the workspace's concurrent-session cap; a fork that does not fit starts no child. minimum: 0 budget_usd: type: - number - 'null' format: double description: 'Spend ceiling per child in USD (default: the parent''s).' title: type: - string - 'null' description: 'Title for the children (default: the parent''s).' SessionForkResponse: type: object required: - object - parent_session_id - checkpoint_id - sessions properties: object: type: string parent_session_id: type: string checkpoint_id: type: string description: The checkpoint every child started from. sessions: type: array items: $ref: '#/components/schemas/SessionResponse' description: |- The children, `provisioning` until each runtime reports `ready`; a child whose sandbox failed to start is listed as `failed`. 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.