Skip to main content
Create independent copies of sessions with all messages, tasks, and configurations intact. Perfect for experimentation, checkpointing, and branching workflows.

​
Use Cases

  • Experimentation: Try different approaches without affecting the original conversation
  • Checkpointing: Save progress at key decision points
  • Branching workflows: Explore parallel conversation paths from a common starting point
  • Template sessions: Reuse successful session patterns

​
Basic Usage

from acontext import AcontextClient
import os

client = AcontextClient(api_key=os.getenv("ACONTEXT_API_KEY"))

# Copy a session
result = client.sessions.copy(session_id="session-uuid")

print(f"Original session: {result.old_session_id}")
print(f"Copied session: {result.new_session_id}")

# Now you can modify the copied session independently
client.sessions.store_message(
    session_id=result.new_session_id,
    blob={"role": "user", "content": "Let's try a different approach"},
    format="openai"
)

​
Async Python SDK

from acontext import AsyncAcontextClient
import os
import asyncio

async def copy_example():
    async with AsyncAcontextClient(api_key=os.getenv("ACONTEXT_API_KEY")) as client:
        result = await client.sessions.copy(session_id="session-uuid")
        print(f"Copied session: {result.new_session_id}")

asyncio.run(copy_example())

​
What Gets Copied

When you copy a session, the following are duplicated:
  • Messages: All messages with preserved parent-child relationships
  • Tasks: All tasks with their order, status, and data
  • Configurations: Session configs and settings
  • User association: The copied session belongs to the same project

​
What Doesn’t Get Copied

  • Asset files: S3 assets are shared (not duplicated) between sessions for efficiency
  • Message processing status: Copied messages are marked as “pending” for reprocessing
  • Task-message links: These are cleared and will be reassigned by the core service

​
Independence

The copied session is completely independent:
  • Changes to the original session don’t affect the copy
  • Changes to the copy don’t affect the original
  • Each session can have different messages, tasks, and configs going forward

​
Limitations

​
Size Limit

Sessions with more than 5,000 messages cannot be copied synchronously. You’ll receive an error: 
{
  "error": "SESSION_TOO_LARGE",
  "message": "Session exceeds maximum copyable size (5000 messages). Consider using async copy."
}
For large sessions, async copy support is planned for a future release.

​
Error Handling

from acontext import AcontextClient
from acontext.exceptions import AcontextError

client = AcontextClient(api_key="...")

try:
    result = client.sessions.copy(session_id="invalid-uuid")
except AcontextError as e:
    if "SESSION_NOT_FOUND" in str(e):
        print("Session does not exist or you don't have access")
    elif "SESSION_TOO_LARGE" in str(e):
        print("Session is too large to copy synchronously")
    else:
        print(f"Copy failed: {e}")

​
Common Patterns

​
Experiment and Compare

Copy a session to try different approaches, then compare results: 
# Copy the original session
result = client.sessions.copy(session_id=original_id)
experimental_id = result.new_session_id

# Try a different approach in the copy
client.sessions.store_message(
    session_id=experimental_id,
    blob={"role": "user", "content": "Alternative approach..."},
    format="openai"
)

# Compare token counts
original = client.sessions.get_token_counts(session_id=original_id)
experimental = client.sessions.get_token_counts(session_id=experimental_id)

print(f"Original: {original.total_tokens} tokens")
print(f"Experimental: {experimental.total_tokens} tokens")

​
Checkpoint Before Major Changes

Create a checkpoint before making significant changes: 
# Create checkpoint
checkpoint = client.sessions.copy(session_id=session_id)
print(f"Checkpoint created: {checkpoint.new_session_id}")

# Make major changes to original
client.sessions.store_message(
    session_id=session_id,
    blob={"role": "user", "content": "Major change..."},
    format="openai"
)

# If needed, you can always go back to the checkpoint

​
Template Sessions

Create a base session as a template and copy it for each new conversation: 
# Set up template session once
template_id = "template-session-uuid"
client.sessions.store_message(
    session_id=template_id,
    blob={"role": "system", "content": "You are a helpful assistant..."},
    format="openai"
)

# Copy for each new conversation
new_conversation = client.sessions.copy(session_id=template_id)

​
Performance

Copy operations typically complete in:
  • < 1 second: Sessions with < 100 messages
  • < 3 seconds: Sessions with < 1000 messages
  • < 5 seconds: Sessions with < 5000 messages
The operation is atomic - either the entire copy succeeds or fails with no partial state.