# Fork a session

Launch stage: Beta

`POST /api/2.0/agents/{parent=session-stores/*}/sessions:fork`

Forks a session into an independent top-level copy.

API scopes: agent-kit

## Path parameters

- `parent` (string, required)
  Resource name of the containing session store, in the form
   `session-stores/{session_store_id}`.

## Request body

- `source_session_id` (string, required)
  ID of the session to copy.
- `up_to_item_id` (string, optional)
  Optional last item ID to copy through, inclusively. When omitted, the fork atomically copies
   all items committed before the fork operation begins.
- `session_id` (string, optional)
  Optional unique ID for the forked session. A collision returns `ALREADY_EXISTS`.
- `actor_id` (string, required)
  Opaque caller-provided identifier for the application actor associated with the forked session.
- `metadata` (object, optional)
  Optional metadata for the fork.

## Returns

- `session` (object, optional)
  The newly-created independent top-level session.
  - `session_id` (string, optional, Output only)
    Unique session ID. The service generates a UUID unless the caller supplies
     `CreateSessionRequest.session_id`.
  - `actor_id` (string, required, Immutable)
    Opaque caller-provided identifier for the application actor associated with the session.
    
     This is application data and has no Databricks authentication or authorization semantics.
     Use the same value as the Managed Memory Entry `actor_id` when storing memories associated
     with this actor. Every session must set it. A child session must use the same value as its parent.
  - `parent_session_id` (string, optional, Immutable)
    Immediate parent session ID. Set only at creation for child sessions, immutable thereafter, and
     restricted to the same store.
  - `root_session_id` (string, optional, Output only)
    Top-level session ID in the spawn tree. This equals `session_id` for a root or fork and is
     inherited transitively by child sessions.
  - `metadata` (object, optional)
    Mutable caller-defined string labels.
  - `create_time` (string, optional, Output only)
    Time when the session was created.
  - `update_time` (string, optional, Output only)
    Time when session resource fields last changed.
  - `last_activity_time` (string, optional, Output only)
    Time when the session's item history was last mutated.
  - `name` (string, optional, Output only, ID, Immutable)
    Resource name in the form `session-stores/{session_store_id}/sessions/{session_id}`.

## Response

```json
{
  "session": {
    "session_id": "string",
    "actor_id": "string",
    "parent_session_id": "string",
    "root_session_id": "string",
    "metadata": {},
    "create_time": "string",
    "update_time": "string",
    "last_activity_time": "string",
    "name": "string"
  }
}
```