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

# 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

<ResponseField name="session_id" type="string" required>
  The ID of the session to update.
</ResponseField>

<ResponseField name="custom_id" type="string" optional>
  The custom ID associated with the session.
</ResponseField>

<ResponseField name="status" type="string" optional>
  The status of the session. Valid values are `PENDING`, `COMPLETED`, `FAILED`.
</ResponseField>

<ResponseField name="context" type="string" optional>
  The context provided to the AI product during the session or ground-truth related context.
</ResponseField>

<ResponseField name="stopping_reason" type="string" optional>
  The reason the session was stopped. Useful for recording why a conversation ended.
</ResponseField>

<ResponseField name="metadata" type="object" optional>
  Additional metadata to associate with the session.
</ResponseField>

<ResponseField name="error" type="string" optional>
  Any error message associated with the session. Useful for tracking failed sessions or sessions that encountered issues.
</ResponseField>

## Returns

Returns the updated `Session` object.

## Example

```python theme={"system"}
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:

```python theme={"system"}
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:

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

## Notes

<Note>
  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.
</Note>

## Related Methods

* [Create Session](/sdk/api/session/create) - Create a new session
* [Get Session](/sdk/api/session/get) - Retrieve a session
* [Get Session By Custom ID](/sdk/api/session/get-by-custom-id) - Retrieve a session by its Custom ID
* [List Sessions](/sdk/api/session/list) - List all sessions