> ## Documentation Index
> Fetch the complete documentation index at: https://docs.freeplay.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

> Create and manage sessions to group related LLM completions together.

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](/core-concepts/observability/sessions-traces-and-completions).

## Methods Overview

| Method | Description          | Python                                    | TypeScript                              | Java/Kotlin                               |
| ------ | -------------------- | ----------------------------------------- | --------------------------------------- | ----------------------------------------- |
| Create | Create a new session | `sessions.create()`                       | `sessions.create({})`                   | `sessions().create()`                     |
| Delete | Delete a session     | `sessions.delete(project_id, session_id)` | `sessions.delete(projectId, sessionId)` | `sessions().delete(projectId, sessionId)` |

## Create a Session

<CodeGroup>
  ```python python theme={null}
  # create a session
  session = fp_client.sessions.create()
  ```

  ```typescript typescript theme={null}
  // create a session
  const session = fpClient.sessions.create({});
  ```

  ```java java theme={null}
  import ai.freeplay.client.thin.Freeplay;
  import ai.freeplay.client.thin.resources.sessions.Session;

  // create a session
  Session session = fpClient.sessions().create();
  ```

  ```kotlin kotlin theme={null}
  val session = fpClient.sessions().create()
  ```
</CodeGroup>

## 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.

<CodeGroup>
  ```python python theme={null}
  # create a session with custom metadata
  session = fp_client.sessions.create(
      custom_metadata={
          "keyA": "valueA",
          "keyB": False
      }
  )
  ```

  ```typescript typescript theme={null}
  // create a session with custom metadata
  const session = fpClient.sessions.create({
    keyA: "valueA",
    keyB: "valueB"
  });
  ```

  ```java java theme={null}
  import ai.freeplay.client.thin.resources.sessions.Session;

  // create a session with Custom Metadata
  Session sessionB = fpClient.sessions().create().customMetadata(Map.of("keyA", "valueA"));
  ```

  ```kotlin kotlin theme={null}
  val session = fpClient.sessions().create()
    .customMetadata(mapOf("keyA" to "valueA"))
  ```
</CodeGroup>

## Delete a Session

<CodeGroup>
  ```python python theme={null}
  project_id = 'bf56b063-80dc-4ad5-91f6-f7067ad1fa06'
  session_id = session.session_id

  fp_client.sessions.delete(project_id, session_id)
  ```

  ```typescript typescript theme={null}
  const projectId = 'bf56b063-80dc-4ad5-91f6-f7067ad1fa06'
  const sessionId = session.sessionId;

  await fpClient.sessions.delete(projectId, sessionId);
  ```

  ```java java theme={null}
  String projectId = "bf56b063-80dc-4ad5-91f6-f7067ad1fa06";
  SessionInfo sessionInfo = fpClient.sessions().create().getSessionInfo();

  fpClient.sessions().delete(projectId, sessionInfo.getSessionId());
  ```
</CodeGroup>

## Using Sessions with Completions

When you record a completion, pass the `session_info` from your session to associate the completion with that session:

<CodeGroup>
  ```python python theme={null}
  session = fp_client.sessions.create()

  # ... make LLM call ...

  fp_client.recordings.create(RecordPayload(
      project_id=project_id,
      session_info=session.session_info,
      # ... other parameters
  ))
  ```

  ```typescript typescript theme={null}
  const session = fpClient.sessions.create({});

  // ... make LLM call ...

  await fpClient.recordings.create({
      projectId,
      sessionInfo: session.sessionInfo,
      // ... other parameters
  });
  ```
</CodeGroup>

For complete recording examples, see [Recording Completions](/freeplay-sdk/recording-completions).