Skip to main content
Sessions are the top-level grouping in Freeplay’s observability hierarchy. Every completion you record belongs to a session—you provide a session ID when recording, and the session is created automatically if it doesn’t already exist.

​
Understanding Sessions

A session represents a logical user interaction or instance of your application running. Think of it as a container that groups related completions together for analysis. The sessions.create() method generates a session ID (UUID v4) and returns a Session object. You can also optionally set custom metadata at creation time. While you could generate your own UUID and let the session be created implicitly when recording your first completion, using sessions.create() is the recommended pattern. Create a new session when:
  • A user starts a new conversation
  • A distinct workflow or task begins
  • A new instance of your application starts handling requests
For more context on sessions vs. traces, see Sessions, Traces, and Completions.

​
Methods Overview

MethodDescriptionPythonTypeScriptJava/Kotlin
CreateCreate a new sessionsessions.create()sessions.create({})sessions().create()
DeleteDelete a sessionsessions.delete(project_id, session_id)sessions.delete(projectId, sessionId)sessions().delete(projectId, sessionId)

​
Create a Session

# create a session
session = fp_client.sessions.create()

​
Custom Metadata

Freeplay enables you to log Custom Metadata associated with any Session. This is fully customizable and can take any arbitrary key-value pairs. The custom_metadata parameter accepts a dictionary (Python) or object (TypeScript/JavaScript) with arbitrary key-value pairs. Use Custom Metadata to record things like customer ID, thread ID, RAG version, Git commit SHA, or any other information you want to track. 
# create a session with custom metadata
session = fp_client.sessions.create(
    custom_metadata={
        "keyA": "valueA",
        "keyB": False
    }
)

​
Delete a Session

project_id = 'bf56b063-80dc-4ad5-91f6-f7067ad1fa06'
session_id = session.session_id

fp_client.sessions.delete(project_id, session_id)

​
Using Sessions with Completions

When you record a completion, pass the session_info from your session to associate the completion with that session: 
session = fp_client.sessions.create()

# ... make LLM call ...

fp_client.recordings.create(RecordPayload(
    project_id=project_id,
    session_info=session.session_info,
    # ... other parameters
))
For complete recording examples, see Recording Completions.