Skip to main content

​
What is a Session?

A session groups the turns of a single conversation between a user and your AI product. It contains one or more traces (input/output pairs) and can be evaluated as a whole using conversational metrics. You create sessions explicitly with sessions.create() for full control over session lifecycle and grouping. If you give a session your own custom_id, you can then reference it by that id when creating a trace: pass it as session_custom_id (with a version_id or product_id anchor) and Galtea appends the turn to that existing session. Production sessions can also be created automatically by ingesting OpenTelemetry traces; see Monitor Real User Traffic via OpenTelemetry. You can create, view, and manage sessions programmatically using the Galtea SDK.

​
SDK Integration

Session Service SDK

Manage sessions using the Python SDK

​
Session Properties

​
Text
required
The custom ID associated with the session. This is usually a client-side generated ID that identifies the conversation session between a user and a LLM app. It is unique per version: logging a trace with a session_custom_id finds the existing session with that custom ID and appends to it (see Create Trace).
​
Version
required
The version associated with the session.
​
Test Case
The test case associated with the session. This is typically used for non-production evaluations.
​
Boolean
Indicates whether the session represents real production traffic. Defaults to True when test_case_id is omitted at creation and False when a test_case_id is provided. Externally-ingested sessions (e.g. imported traces) may be classified as non-production without supplying a test_case_id. The only forbidden combination is test_case_id set together with is_production=True. When test_case_id is set, the session context is derived from the test case; otherwise the context from the request is used directly.
​
Text
The context provided to the AI product during the session or ground-truth related context. For production sessions, this value is taken from the request. For non-production sessions, it is derived from the linked test case.
​
Object
Additional custom metadata about the session. This can be used to store any relevant information that doesn’t fit into the other fields.
​
Enum
The lifecycle state of the session, and the single signal for whether it is open or closed.
  • PENDING (open): the session accepts new turns. Every session starts here.
  • COMPLETED (closed): the session finished successfully.
  • FAILED (closed): the session ended with an error.
A session stays PENDING until it closes. It closes when you finish it explicitly with sessions.finish(), or when the product’s auto-close setting closes it after a window of inactivity. On a default-configured product, calling finish() is the normal way to complete a session. A closed production session goes back to PENDING when a new turn arrives, unless you change the product’s closed-session policy. See Session Lifecycle for the full open/closed model and what happens to a turn that arrives after the session closes.
​
Text
Human-readable text describing why the conversation ended, for example “Automatically closed after 30 minutes of inactivity”. It is a label for people to read: it does not lock the session or drive any behavior. The session Status alone decides whether the session is open or closed.
​
Text
Any error message associated with the session. This is useful for tracking failed sessions or sessions that encountered issues.
​
Text
The canonical storage URI of the full-call recording for telephony sessions. This field is read-only and populated by the API after a phone-call session’s recording is captured and processed. Null for non-telephony sessions or before the recording is available. Resolve to a playable URL via the storage endpoint.

​
Session Lifecycle

A session is either open or closed, and its Status is the single source of truth for which one it is:
  • Open (PENDING): the session accepts new turns. Every new session starts open by default.
  • Closed (COMPLETED or FAILED): the session is finished. What a later turn does to it depends on the product’s closed-session policy, described below.

​
How a session closes

A session becomes closed in one of two ways:
  • Explicit finish. You end the session on purpose, and it closes right away. Call sessions.finish() from the SDK: it records a Stopping Reason and sets the status to COMPLETED. The endpoint behind it (PATCH /sessions/{id}/finish) also accepts an error instead, which closes the session as FAILED.
  • Auto-close sweep. Galtea runs a background job that closes quiet sessions for you. It closes an open session once its most recent trace is older than the product’s inactivity window, and writes a Stopping Reason such as “Automatically closed after 30 minutes of inactivity” so you can tell an auto-close from an explicit finish. The sweep only closes open sessions; it never changes one that is already closed.
You configure auto-close per product with three fields: Auto Close Scope (which sessions the sweep closes: NONE, DEVELOPMENT, PRODUCTION, or ALL), Auto Close Inactivity Minutes (the quiet window), and Closed Session Inference Creation Policy (what happens to a late turn, see below). See the Product properties for the exact fields and defaults; set them from the API or the dashboard. By default the scope is PRODUCTION, so production sessions auto-close after the window while development (test) sessions stay open until you finish them.

​
Turns that arrive after a session closes

When a new trace arrives for a closed session, the product’s Closed Session Inference Creation Policy decides what happens:
  • REOPEN_AND_REEVALUATE (the default): the API stores the turn and opens the session again. The status goes back to PENDING, so the auto-close sweep closes the session again later. The session’s existing monitor evaluations move to the OUTDATED status, so their scores stop counting as current, and a Monitor scores the session again once it closes. Only production sessions reopen. A development (test) session behaves as with IGNORE, because a monitor scores only production sessions.
  • IGNORE: the API accepts the call, returns success, and stores nothing. The late turn is silently dropped.
  • REJECT: the API refuses the call and returns an error.
The default keeps every late turn, so a user who replies after a long gap does not lose that turn. If you set the policy to IGNORE or REJECT and still want late turns kept, raise the inactivity window or set the scope so those sessions are not auto-closed. The Monitor Production Responses tutorial walks through this trade-off.

Concepts overview

How Galtea’s concepts connect — diagram + per-entity quick reference.

Evaluation

Learn how evaluations score traces within a session.

Trace

Understand the input/output pairs that make up a session.

Simulating Conversations

Tutorial on running multi-turn conversation simulations.