Get Or Create Session

Get an existing session or create a new one if it doesn’t exist.

Returns

Returns a Session object.

Example

session = galtea.sessions.get_or_create(
    custom_id=custom_session_id,
    version_id=version_id,
    test_case_id=test_case_id,
    metadata={"authenticated_user_id": "user-123"},
)

Parameters

custom_id · string · required

The Custom ID of the session to fetch or create.

This is useful to associate sessions in the Galtea platform with those in your application. It is unique only per version, so a version_id or product_id anchor is required to resolve it unambiguously.

version_id · string

The version to look the session up on, and to associate with it if it needs to be created.

Provide version_id or product_id (at least one is required) — both for the lookup and if the session needs to be created. If both are given, version_id wins and product_id is ignored.

product_id · string

The product to search across (any of its versions) for the lookup, and to associate with this session if it needs to be created, as an alternative to version_id. If more than one version has a session with this custom ID, the most recently created one is returned. When creating, the API resolves the product’s latest version, or creates a default one if the product has none yet.

Provide version_id or product_id (at least one is required) — both for the lookup and if the session needs to be created. If both are given, version_id wins and product_id is ignored.

test_case_id · string

The test case ID. Forbidden when is_production=True. A non-production session may be created without a test case (e.g. externally ingested traces) — the context will then come from the request rather than the test case.

context · str

Additional context for the session. Forbidden when test_case_id is set (the context is derived from the test case).

is_production · boolean

A flag to indicate if the session represents real production traffic. When omitted on a newly created session, the API derives it from test_case_id presence: no test case means production.

metadata · object

Arbitrary key/value metadata to attach to the session. Applied only when a new session is created; if the session already exists, it is returned unchanged and this value is ignored. Useful, for example, to record who is chatting via metadata={"authenticated_user_id": ...}.