# Chat

## List Sessions

`$ llamacloud-prod beta:chat list`

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

List all chat sessions for the current project.

### Parameters

- `--organization-id: optional string`

- `--page-size: optional number`

- `--page-token: optional string`

- `--project-id: optional string`

### Returns

- `SessionListAPIResponse: object { items, next_page_token }`

  Paginated list of chat sessions.

  - `items: array of object { last_updated_at, session_id, generated_title, 2 more }`

    Chat sessions for the current page.

    - `last_updated_at: string`

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

    - `session_id: string`

      Unique session identifier.

    - `generated_title: optional string`

      Auto-generated title derived from the first user message.

    - `index_ids: optional array of string`

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

    - `job_metadata: optional object { duration_ms, error, export_config_ids, 4 more }`

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

      - `duration_ms: optional number`

      - `error: optional string`

      - `export_config_ids: optional array of string`

      - `is_error: optional boolean`

      - `total_input_tokens: optional number`

      - `total_output_tokens: optional number`

      - `turns: optional number`

  - `next_page_token: optional string`

    Opaque token to retrieve the next page. Omitted when there are no further pages.

### Example

```cli
llamacloud-prod beta:chat list \
  --api-key 'My API Key'
```

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

`$ llamacloud-prod beta:chat create`

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

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

### Parameters

- `--organization-id: optional string`

  Query param

- `--project-id: optional string`

  Query param

- `--index-id: optional array of string`

  Body param: 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

- `BetaChatNewResponse: object { last_updated_at, session_id, generated_title, 2 more }`

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

  - `last_updated_at: string`

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

  - `session_id: string`

    Unique session identifier.

  - `generated_title: optional string`

    Auto-generated title derived from the first user message.

  - `index_ids: optional array of string`

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

  - `job_metadata: optional object { duration_ms, error, export_config_ids, 4 more }`

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

    - `duration_ms: optional number`

    - `error: optional string`

    - `export_config_ids: optional array of string`

    - `is_error: optional boolean`

    - `total_input_tokens: optional number`

    - `total_output_tokens: optional number`

    - `turns: optional number`

### Example

```cli
llamacloud-prod beta:chat create \
  --api-key 'My API Key'
```

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

`$ llamacloud-prod beta:chat retrieve`

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

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

### Parameters

- `--session-id: string`

- `--organization-id: optional string`

- `--project-id: optional string`

### Returns

- `BetaChatGetResponse: object { events, last_updated_at, session_id, 3 more }`

  Full chat session including its complete event history.

  - `events: array of object { content, type }  or object { content, type }  or object { content, type }  or 5 more`

    Ordered list of events that make up the conversation history.

    - `thinking_delta: object { content, type }`

      - `content: string`

      - `type: optional "thinking_delta"`

        - `"thinking_delta"`

    - `text_delta: object { content, type }`

      - `content: string`

      - `type: optional "text_delta"`

        - `"text_delta"`

    - `thinking: object { content, type }`

      - `content: string`

      - `type: optional "thinking"`

        - `"thinking"`

    - `text: object { content, type }`

      - `content: string`

      - `type: optional "text"`

        - `"text"`

    - `tool_call: object { arguments, call_id, name, type }`

      - `arguments: map[unknown]`

      - `call_id: string`

      - `name: string`

      - `type: optional "tool_call"`

        - `"tool_call"`

    - `tool_result: object { call_id, name, result, 2 more }`

      - `call_id: string`

      - `name: string`

      - `result: unknown`

      - `image_attachment: optional object { attachment_name, source_id }`

        Coordinates for lazily resolving a page screenshot presigned URL.

        - `attachment_name: string`

        - `source_id: string`

      - `type: optional "tool_result"`

        - `"tool_result"`

    - `stop: object { error, is_error, usage, type }`

      - `error: string`

      - `is_error: boolean`

      - `usage: object { duration_ms, total_input_tokens, total_output_tokens, turns }`

        - `duration_ms: optional number`

        - `total_input_tokens: optional number`

        - `total_output_tokens: optional number`

        - `turns: optional number`

      - `type: optional "stop"`

        - `"stop"`

    - `user_input: object { content, type }`

      - `content: string`

      - `type: optional "user_input"`

        - `"user_input"`

  - `last_updated_at: string`

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

  - `session_id: string`

    Unique session identifier.

  - `generated_title: optional string`

    Auto-generated title derived from the first user message.

  - `index_ids: optional array of string`

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

  - `job_metadata: optional object { duration_ms, error, export_config_ids, 4 more }`

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

    - `duration_ms: optional number`

    - `error: optional string`

    - `export_config_ids: optional array of string`

    - `is_error: optional boolean`

    - `total_input_tokens: optional number`

    - `total_output_tokens: optional number`

    - `turns: optional number`

### Example

```cli
llamacloud-prod beta:chat retrieve \
  --api-key 'My API Key' \
  --session-id 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

`$ llamacloud-prod beta:chat delete`

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

Delete a session.

### Parameters

- `--session-id: string`

- `--organization-id: optional string`

- `--project-id: optional string`

### Example

```cli
llamacloud-prod beta:chat delete \
  --api-key 'My API Key' \
  --session-id session_id
```

## Get Session Summary

`$ llamacloud-prod beta:chat get-summary`

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

Retrieve a session summary by ID.

### Parameters

- `--session-id: string`

- `--organization-id: optional string`

- `--project-id: optional string`

### Returns

- `BetaChatGetSummaryResponse: object { last_updated_at, session_id, generated_title, 2 more }`

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

  - `last_updated_at: string`

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

  - `session_id: string`

    Unique session identifier.

  - `generated_title: optional string`

    Auto-generated title derived from the first user message.

  - `index_ids: optional array of string`

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

  - `job_metadata: optional object { duration_ms, error, export_config_ids, 4 more }`

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

    - `duration_ms: optional number`

    - `error: optional string`

    - `export_config_ids: optional array of string`

    - `is_error: optional boolean`

    - `total_input_tokens: optional number`

    - `total_output_tokens: optional number`

    - `turns: optional number`

### Example

```cli
llamacloud-prod beta:chat get-summary \
  --api-key 'My API Key' \
  --session-id 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

`$ llamacloud-prod beta:chat set-title`

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

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

### Parameters

- `--session-id: string`

  Path param

- `--first-message: string`

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

- `--organization-id: optional string`

  Query param

- `--project-id: optional string`

  Query param

### Returns

- `BetaChatSetTitleResponse: object { last_updated_at, session_id, generated_title, 2 more }`

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

  - `last_updated_at: string`

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

  - `session_id: string`

    Unique session identifier.

  - `generated_title: optional string`

    Auto-generated title derived from the first user message.

  - `index_ids: optional array of string`

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

  - `job_metadata: optional object { duration_ms, error, export_config_ids, 4 more }`

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

    - `duration_ms: optional number`

    - `error: optional string`

    - `export_config_ids: optional array of string`

    - `is_error: optional boolean`

    - `total_input_tokens: optional number`

    - `total_output_tokens: optional number`

    - `turns: optional number`

### Example

```cli
llamacloud-prod beta:chat set-title \
  --api-key 'My API Key' \
  --session-id session_id \
  --first-message 'What were the main findings in Q3?'
```

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

`$ llamacloud-prod beta:chat stream`

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

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

### Parameters

- `--session-id: string`

  Path param

- `--index-id: array of string`

  Body param: Indexes to retrieve data from.

- `--prompt: string`

  Body param: User message for this chat turn.

- `--organization-id: optional string`

  Query param

- `--project-id: optional string`

  Query param

### Returns

- `BetaChatStreamResponse: unknown`

### Example

```cli
llamacloud-prod beta:chat stream \
  --api-key 'My API Key' \
  --session-id session_id \
  --index-id idx-abc123 \
  --index-id idx-def456 \
  --prompt 'What were the main findings in Q3?'
```

#### Response

```json
{}
```