# Chat

## List Sessions

`beta.chat.list(ChatListParams**kwargs)  -> SyncPaginatedCursor[ChatListResponse]`

**get** `/api/v1/chat`

List all chat sessions for the current project.

### Parameters

- `organization_id: Optional[str]`

- `page_size: Optional[int]`

- `page_token: Optional[str]`

- `project_id: Optional[str]`

### Returns

- `class ChatListResponse: …`

  Summary of a chat session, including its title and last run metadata.

  - `last_updated_at: str`

    ISO-format timestamp showing when the session was last updated.

  - `session_id: str`

    Unique session identifier.

  - `generated_title: Optional[str]`

    Auto-generated title derived from the first user message.

  - `index_ids: Optional[List[str]]`

    Indexes this session is bound to. Null on unbound sessions.

  - `job_metadata: Optional[JobMetadata]`

    Token usage and status from the most recent run. Null if the session has not been run yet.

    - `duration_ms: Optional[float]`

    - `error: Optional[str]`

    - `export_config_ids: Optional[List[str]]`

    - `is_error: Optional[bool]`

    - `total_input_tokens: Optional[int]`

    - `total_output_tokens: Optional[int]`

    - `turns: Optional[int]`

### Example

```python
import os
from llama_cloud import LlamaCloud

client = LlamaCloud(
    api_key=os.environ.get("LLAMA_CLOUD_API_KEY"),  # This is the default and can be omitted
)
page = client.beta.chat.list()
page = page.items[0]
print(page.session_id)
```

#### Response

```json
{
  "items": [
    {
      "last_updated_at": "2026-04-22T12:34:41.342245",
      "session_id": "ses-abc123",
      "generated_title": "What were the main findings in Q3?...",
      "index_ids": [
        "idx-abc123",
        "idx-def456"
      ],
      "job_metadata": {
        "duration_ms": 0,
        "error": "error",
        "export_config_ids": [
          "string"
        ],
        "is_error": true,
        "total_input_tokens": 0,
        "total_output_tokens": 0,
        "turns": 0
      }
    }
  ],
  "next_page_token": "next_page_token"
}
```

## Create Session

`beta.chat.create(ChatCreateParams**kwargs)  -> ChatCreateResponse`

**post** `/api/v1/chat`

Create a chat session, optionally bound to indexes (locked after the first message).

### Parameters

- `organization_id: Optional[str]`

- `project_id: Optional[str]`

- `index_ids: Optional[SequenceNotStr[str]]`

  Indexes this session will retrieve from. Once set and the first message has been sent, the source set is locked for the session's lifetime. Leave null to create an unbound session.

### Returns

- `class ChatCreateResponse: …`

  Summary of a chat session, including its title and last run metadata.

  - `last_updated_at: str`

    ISO-format timestamp showing when the session was last updated.

  - `session_id: str`

    Unique session identifier.

  - `generated_title: Optional[str]`

    Auto-generated title derived from the first user message.

  - `index_ids: Optional[List[str]]`

    Indexes this session is bound to. Null on unbound sessions.

  - `job_metadata: Optional[JobMetadata]`

    Token usage and status from the most recent run. Null if the session has not been run yet.

    - `duration_ms: Optional[float]`

    - `error: Optional[str]`

    - `export_config_ids: Optional[List[str]]`

    - `is_error: Optional[bool]`

    - `total_input_tokens: Optional[int]`

    - `total_output_tokens: Optional[int]`

    - `turns: Optional[int]`

### Example

```python
import os
from llama_cloud import LlamaCloud

client = LlamaCloud(
    api_key=os.environ.get("LLAMA_CLOUD_API_KEY"),  # This is the default and can be omitted
)
chat = client.beta.chat.create()
print(chat.session_id)
```

#### Response

```json
{
  "last_updated_at": "2026-04-22T12:34:41.342245",
  "session_id": "ses-abc123",
  "generated_title": "What were the main findings in Q3?...",
  "index_ids": [
    "idx-abc123",
    "idx-def456"
  ],
  "job_metadata": {
    "duration_ms": 0,
    "error": "error",
    "export_config_ids": [
      "string"
    ],
    "is_error": true,
    "total_input_tokens": 0,
    "total_output_tokens": 0,
    "turns": 0
  }
}
```

## Get Full Session

`beta.chat.retrieve(strsession_id, ChatRetrieveParams**kwargs)  -> ChatRetrieveResponse`

**get** `/api/v1/chat/{session_id}`

Retrieve a full session by ID, including its event history.

### Parameters

- `session_id: str`

- `organization_id: Optional[str]`

- `project_id: Optional[str]`

### Returns

- `class ChatRetrieveResponse: …`

  Full chat session including its complete event history.

  - `events: List[Event]`

    Ordered list of events that make up the conversation history.

    - `class EventThinkingDeltaEvent: …`

      - `content: str`

      - `type: Optional[Literal["thinking_delta"]]`

        - `"thinking_delta"`

    - `class EventTextDeltaEvent: …`

      - `content: str`

      - `type: Optional[Literal["text_delta"]]`

        - `"text_delta"`

    - `class EventThinkingEvent: …`

      - `content: str`

      - `type: Optional[Literal["thinking"]]`

        - `"thinking"`

    - `class EventTextEvent: …`

      - `content: str`

      - `type: Optional[Literal["text"]]`

        - `"text"`

    - `class EventToolCallEvent: …`

      - `arguments: Dict[str, object]`

      - `call_id: str`

      - `name: str`

      - `type: Optional[Literal["tool_call"]]`

        - `"tool_call"`

    - `class EventToolResultEvent: …`

      - `call_id: str`

      - `name: str`

      - `result: object`

      - `image_attachment: Optional[EventToolResultEventImageAttachment]`

        Coordinates for lazily resolving a page screenshot presigned URL.

        - `attachment_name: str`

        - `source_id: str`

      - `type: Optional[Literal["tool_result"]]`

        - `"tool_result"`

    - `class EventStopEvent: …`

      - `error: Optional[str]`

      - `is_error: bool`

      - `usage: EventStopEventUsage`

        - `duration_ms: Optional[float]`

        - `total_input_tokens: Optional[int]`

        - `total_output_tokens: Optional[int]`

        - `turns: Optional[int]`

      - `type: Optional[Literal["stop"]]`

        - `"stop"`

    - `class EventUserInputEvent: …`

      - `content: str`

      - `type: Optional[Literal["user_input"]]`

        - `"user_input"`

  - `last_updated_at: str`

    ISO-format timestamp showing when the session was last updated.

  - `session_id: str`

    Unique session identifier.

  - `generated_title: Optional[str]`

    Auto-generated title derived from the first user message.

  - `index_ids: Optional[List[str]]`

    Indexes this session is bound to. Null on unbound sessions.

  - `job_metadata: Optional[JobMetadata]`

    Token usage and status from the most recent run. Null if the session has not been run yet.

    - `duration_ms: Optional[float]`

    - `error: Optional[str]`

    - `export_config_ids: Optional[List[str]]`

    - `is_error: Optional[bool]`

    - `total_input_tokens: Optional[int]`

    - `total_output_tokens: Optional[int]`

    - `turns: Optional[int]`

### Example

```python
import os
from llama_cloud import LlamaCloud

client = LlamaCloud(
    api_key=os.environ.get("LLAMA_CLOUD_API_KEY"),  # This is the default and can be omitted
)
chat = client.beta.chat.retrieve(
    session_id="session_id",
)
print(chat.session_id)
```

#### Response

```json
{
  "events": [
    {
      "content": "content",
      "type": "thinking_delta"
    }
  ],
  "last_updated_at": "2026-04-22T12:34:41.342245",
  "session_id": "ses-abc123",
  "generated_title": "What were the main findings in Q3?...",
  "index_ids": [
    "idx-abc123",
    "idx-def456"
  ],
  "job_metadata": {
    "duration_ms": 0,
    "error": "error",
    "export_config_ids": [
      "string"
    ],
    "is_error": true,
    "total_input_tokens": 0,
    "total_output_tokens": 0,
    "turns": 0
  }
}
```

## Delete Session

`beta.chat.delete(strsession_id, ChatDeleteParams**kwargs)`

**delete** `/api/v1/chat/{session_id}`

Delete a session.

### Parameters

- `session_id: str`

- `organization_id: Optional[str]`

- `project_id: Optional[str]`

### Example

```python
import os
from llama_cloud import LlamaCloud

client = LlamaCloud(
    api_key=os.environ.get("LLAMA_CLOUD_API_KEY"),  # This is the default and can be omitted
)
client.beta.chat.delete(
    session_id="session_id",
)
```

## Get Session Summary

`beta.chat.get_summary(strsession_id, ChatGetSummaryParams**kwargs)  -> ChatGetSummaryResponse`

**get** `/api/v1/chat/{session_id}/summary`

Retrieve a session summary by ID.

### Parameters

- `session_id: str`

- `organization_id: Optional[str]`

- `project_id: Optional[str]`

### Returns

- `class ChatGetSummaryResponse: …`

  Summary of a chat session, including its title and last run metadata.

  - `last_updated_at: str`

    ISO-format timestamp showing when the session was last updated.

  - `session_id: str`

    Unique session identifier.

  - `generated_title: Optional[str]`

    Auto-generated title derived from the first user message.

  - `index_ids: Optional[List[str]]`

    Indexes this session is bound to. Null on unbound sessions.

  - `job_metadata: Optional[JobMetadata]`

    Token usage and status from the most recent run. Null if the session has not been run yet.

    - `duration_ms: Optional[float]`

    - `error: Optional[str]`

    - `export_config_ids: Optional[List[str]]`

    - `is_error: Optional[bool]`

    - `total_input_tokens: Optional[int]`

    - `total_output_tokens: Optional[int]`

    - `turns: Optional[int]`

### Example

```python
import os
from llama_cloud import LlamaCloud

client = LlamaCloud(
    api_key=os.environ.get("LLAMA_CLOUD_API_KEY"),  # This is the default and can be omitted
)
response = client.beta.chat.get_summary(
    session_id="session_id",
)
print(response.session_id)
```

#### Response

```json
{
  "last_updated_at": "2026-04-22T12:34:41.342245",
  "session_id": "ses-abc123",
  "generated_title": "What were the main findings in Q3?...",
  "index_ids": [
    "idx-abc123",
    "idx-def456"
  ],
  "job_metadata": {
    "duration_ms": 0,
    "error": "error",
    "export_config_ids": [
      "string"
    ],
    "is_error": true,
    "total_input_tokens": 0,
    "total_output_tokens": 0,
    "turns": 0
  }
}
```

## Generate Session Title

`beta.chat.set_title(strsession_id, ChatSetTitleParams**kwargs)  -> ChatSetTitleResponse`

**post** `/api/v1/chat/{session_id}/title`

Generate a title for a session from its first user message.

### Parameters

- `session_id: str`

- `first_message: str`

  First user message of the session, used to infer a short title.

- `organization_id: Optional[str]`

- `project_id: Optional[str]`

### Returns

- `class ChatSetTitleResponse: …`

  Summary of a chat session, including its title and last run metadata.

  - `last_updated_at: str`

    ISO-format timestamp showing when the session was last updated.

  - `session_id: str`

    Unique session identifier.

  - `generated_title: Optional[str]`

    Auto-generated title derived from the first user message.

  - `index_ids: Optional[List[str]]`

    Indexes this session is bound to. Null on unbound sessions.

  - `job_metadata: Optional[JobMetadata]`

    Token usage and status from the most recent run. Null if the session has not been run yet.

    - `duration_ms: Optional[float]`

    - `error: Optional[str]`

    - `export_config_ids: Optional[List[str]]`

    - `is_error: Optional[bool]`

    - `total_input_tokens: Optional[int]`

    - `total_output_tokens: Optional[int]`

    - `turns: Optional[int]`

### Example

```python
import os
from llama_cloud import LlamaCloud

client = LlamaCloud(
    api_key=os.environ.get("LLAMA_CLOUD_API_KEY"),  # This is the default and can be omitted
)
response = client.beta.chat.set_title(
    session_id="session_id",
    first_message="What were the main findings in Q3?",
)
print(response.session_id)
```

#### Response

```json
{
  "last_updated_at": "2026-04-22T12:34:41.342245",
  "session_id": "ses-abc123",
  "generated_title": "What were the main findings in Q3?...",
  "index_ids": [
    "idx-abc123",
    "idx-def456"
  ],
  "job_metadata": {
    "duration_ms": 0,
    "error": "error",
    "export_config_ids": [
      "string"
    ],
    "is_error": true,
    "total_input_tokens": 0,
    "total_output_tokens": 0,
    "turns": 0
  }
}
```

## Stream Messages

`beta.chat.stream(strsession_id, ChatStreamParams**kwargs)  -> object`

**post** `/api/v1/chat/{session_id}/messages/stream`

Stream agent events for a chat turn as Server-Sent Events.

### Parameters

- `session_id: str`

- `index_ids: SequenceNotStr[str]`

  Indexes to retrieve data from.

- `prompt: str`

  User message for this chat turn.

- `organization_id: Optional[str]`

- `project_id: Optional[str]`

### Returns

- `object`

### Example

```python
import os
from llama_cloud import LlamaCloud

client = LlamaCloud(
    api_key=os.environ.get("LLAMA_CLOUD_API_KEY"),  # This is the default and can be omitted
)
response = client.beta.chat.stream(
    session_id="session_id",
    index_ids=["idx-abc123", "idx-def456"],
    prompt="What were the main findings in Q3?",
)
print(response)
```

#### Response

```json
{}
```

## Domain Types

### Chat List Response

- `class ChatListResponse: …`

  Summary of a chat session, including its title and last run metadata.

  - `last_updated_at: str`

    ISO-format timestamp showing when the session was last updated.

  - `session_id: str`

    Unique session identifier.

  - `generated_title: Optional[str]`

    Auto-generated title derived from the first user message.

  - `index_ids: Optional[List[str]]`

    Indexes this session is bound to. Null on unbound sessions.

  - `job_metadata: Optional[JobMetadata]`

    Token usage and status from the most recent run. Null if the session has not been run yet.

    - `duration_ms: Optional[float]`

    - `error: Optional[str]`

    - `export_config_ids: Optional[List[str]]`

    - `is_error: Optional[bool]`

    - `total_input_tokens: Optional[int]`

    - `total_output_tokens: Optional[int]`

    - `turns: Optional[int]`

### Chat Create Response

- `class ChatCreateResponse: …`

  Summary of a chat session, including its title and last run metadata.

  - `last_updated_at: str`

    ISO-format timestamp showing when the session was last updated.

  - `session_id: str`

    Unique session identifier.

  - `generated_title: Optional[str]`

    Auto-generated title derived from the first user message.

  - `index_ids: Optional[List[str]]`

    Indexes this session is bound to. Null on unbound sessions.

  - `job_metadata: Optional[JobMetadata]`

    Token usage and status from the most recent run. Null if the session has not been run yet.

    - `duration_ms: Optional[float]`

    - `error: Optional[str]`

    - `export_config_ids: Optional[List[str]]`

    - `is_error: Optional[bool]`

    - `total_input_tokens: Optional[int]`

    - `total_output_tokens: Optional[int]`

    - `turns: Optional[int]`

### Chat Retrieve Response

- `class ChatRetrieveResponse: …`

  Full chat session including its complete event history.

  - `events: List[Event]`

    Ordered list of events that make up the conversation history.

    - `class EventThinkingDeltaEvent: …`

      - `content: str`

      - `type: Optional[Literal["thinking_delta"]]`

        - `"thinking_delta"`

    - `class EventTextDeltaEvent: …`

      - `content: str`

      - `type: Optional[Literal["text_delta"]]`

        - `"text_delta"`

    - `class EventThinkingEvent: …`

      - `content: str`

      - `type: Optional[Literal["thinking"]]`

        - `"thinking"`

    - `class EventTextEvent: …`

      - `content: str`

      - `type: Optional[Literal["text"]]`

        - `"text"`

    - `class EventToolCallEvent: …`

      - `arguments: Dict[str, object]`

      - `call_id: str`

      - `name: str`

      - `type: Optional[Literal["tool_call"]]`

        - `"tool_call"`

    - `class EventToolResultEvent: …`

      - `call_id: str`

      - `name: str`

      - `result: object`

      - `image_attachment: Optional[EventToolResultEventImageAttachment]`

        Coordinates for lazily resolving a page screenshot presigned URL.

        - `attachment_name: str`

        - `source_id: str`

      - `type: Optional[Literal["tool_result"]]`

        - `"tool_result"`

    - `class EventStopEvent: …`

      - `error: Optional[str]`

      - `is_error: bool`

      - `usage: EventStopEventUsage`

        - `duration_ms: Optional[float]`

        - `total_input_tokens: Optional[int]`

        - `total_output_tokens: Optional[int]`

        - `turns: Optional[int]`

      - `type: Optional[Literal["stop"]]`

        - `"stop"`

    - `class EventUserInputEvent: …`

      - `content: str`

      - `type: Optional[Literal["user_input"]]`

        - `"user_input"`

  - `last_updated_at: str`

    ISO-format timestamp showing when the session was last updated.

  - `session_id: str`

    Unique session identifier.

  - `generated_title: Optional[str]`

    Auto-generated title derived from the first user message.

  - `index_ids: Optional[List[str]]`

    Indexes this session is bound to. Null on unbound sessions.

  - `job_metadata: Optional[JobMetadata]`

    Token usage and status from the most recent run. Null if the session has not been run yet.

    - `duration_ms: Optional[float]`

    - `error: Optional[str]`

    - `export_config_ids: Optional[List[str]]`

    - `is_error: Optional[bool]`

    - `total_input_tokens: Optional[int]`

    - `total_output_tokens: Optional[int]`

    - `turns: Optional[int]`

### Chat Get Summary Response

- `class ChatGetSummaryResponse: …`

  Summary of a chat session, including its title and last run metadata.

  - `last_updated_at: str`

    ISO-format timestamp showing when the session was last updated.

  - `session_id: str`

    Unique session identifier.

  - `generated_title: Optional[str]`

    Auto-generated title derived from the first user message.

  - `index_ids: Optional[List[str]]`

    Indexes this session is bound to. Null on unbound sessions.

  - `job_metadata: Optional[JobMetadata]`

    Token usage and status from the most recent run. Null if the session has not been run yet.

    - `duration_ms: Optional[float]`

    - `error: Optional[str]`

    - `export_config_ids: Optional[List[str]]`

    - `is_error: Optional[bool]`

    - `total_input_tokens: Optional[int]`

    - `total_output_tokens: Optional[int]`

    - `turns: Optional[int]`

### Chat Set Title Response

- `class ChatSetTitleResponse: …`

  Summary of a chat session, including its title and last run metadata.

  - `last_updated_at: str`

    ISO-format timestamp showing when the session was last updated.

  - `session_id: str`

    Unique session identifier.

  - `generated_title: Optional[str]`

    Auto-generated title derived from the first user message.

  - `index_ids: Optional[List[str]]`

    Indexes this session is bound to. Null on unbound sessions.

  - `job_metadata: Optional[JobMetadata]`

    Token usage and status from the most recent run. Null if the session has not been run yet.

    - `duration_ms: Optional[float]`

    - `error: Optional[str]`

    - `export_config_ids: Optional[List[str]]`

    - `is_error: Optional[bool]`

    - `total_input_tokens: Optional[int]`

    - `total_output_tokens: Optional[int]`

    - `turns: Optional[int]`