Update Session

Update an existing session with metadata and status information

Overview

The update() method allows you to modify an existing session after it has been created. This is useful when you need to update session metadata, status, or other properties.

Parameters

session_id · string · required

The ID of the session to update.

custom_id · string

The custom ID associated with the session.

status · string

The status of the session. Valid values are PENDING, COMPLETED, FAILED. Other string values are sent to the API unchanged, so values added in newer API versions can be used; the API rejects invalid ones.

context · string

The context provided to the AI product during the session or ground-truth related context.

stopping_reason · string

The reason the session was stopped. Useful for recording why a conversation ended.

metadata · object

Additional metadata to associate with the session.

error · string

Any error message associated with the session. Useful for tracking failed sessions or sessions that encountered issues.

Returns

Returns the updated Session object.

Example

updated_session = galtea.sessions.update(
    session_id=session_id,
    custom_id=custom_session_id + "_" + run_identifier,
    metadata={"updated_at": run_identifier},
)

Use Cases

Recording Session Errors

Store error information when a session encounters issues:

try:
    # Your agent logic that might fail
    raise Exception("Connection timeout")
except Exception as e:
    # Record the error in the session
    galtea.sessions.update(
        session_id=session.id,
        error=str(e),
    )

Adding Session Metadata

Update a session with additional metadata:

galtea.sessions.update(
    session_id=session.id,
    metadata={
        "user_tier": "premium",
        "source": "mobile_app",
        "language": "en",
    },
)

Notes

All fields except session_id default to PydanticUndefined (from pydantic_core). Omit a field (or pass PydanticUndefined) to leave it unchanged. Pass None to explicitly clear an optional field. Pass a value to update it.

Related Methods

• Create Session - Create a new session
• Get Session - Retrieve a session
• Get Session By Custom ID - Retrieve a session by its Custom ID
• List Sessions - List all sessions