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

> [!WARNING]
>
> You are reading the docs of Galtea 5.16. [Read this page in the latest version](https://docs.galtea.ai/sdk/api/session/update.md).

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

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

## Related Methods

* [Create Session](https://docs.galtea.ai/v5.16/sdk/api/session/create.md) - Create a new session
* [Finish Session](https://docs.galtea.ai/v5.16/sdk/api/session/finish.md) - Close a session so it becomes eligible for evaluation
* [Get Session](https://docs.galtea.ai/v5.16/sdk/api/session/get.md) - Retrieve a session
* [Get Session By Custom ID](https://docs.galtea.ai/v5.16/sdk/api/session/get-by-custom-id.md) - Retrieve a session by its Custom ID
* [List Sessions](https://docs.galtea.ai/v5.16/sdk/api/session/list.md) - List all sessions


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.