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

# List User Chats

## List User Chats

This endpoint retrieves all chat sessions for a specific user within your tenant.

## Authentication

<ParamField header="X-API-Key" type="string" required>
  Authentication header with your tenant's API key
</ParamField>

## Path Parameters

<ParamField path="user_id" type="string" required>
  The ID of the user whose chats you want to retrieve
</ParamField>

## Query Parameters

<ParamField query="offset" type="integer" default="0">
  The number of items to skip before starting to collect results
</ParamField>

<ParamField query="limit" type="integer" default="50">
  The maximum number of chats to return
</ParamField>

<ParamField query="order" type="string" default="desc">
  Sort order for chats by creation date. Options: 'asc' or 'desc'
</ParamField>

## Response

<ResponseField name="chats" type="array">
  Array of chat objects belonging to the user
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of chats for this user
</ResponseField>

<ResponseField name="offset" type="integer">
  Current offset value used for pagination
</ResponseField>

<ResponseField name="limit" type="integer">
  Current limit value used for pagination
</ResponseField>

<ResponseField name="has_more" type="boolean">
  Indicates if there are more chats available
</ResponseField>

### Chat Object

<ResponseField name="id" type="string">
  Unique identifier for the chat session
</ResponseField>

<ResponseField name="user_id" type="string">
  The ID of the user who owns this chat
</ResponseField>

<ResponseField name="tenant_id" type="string">
  The tenant identifier
</ResponseField>

<ResponseField name="title" type="string">
  The title of the chat session
</ResponseField>

<ResponseField name="config" type="object">
  Configuration object containing metadata and chat settings
</ResponseField>

<ResponseField name="created_at" type="string" format="date-time">
  Timestamp when the chat was created
</ResponseField>

<ResponseField name="updated_at" type="string" format="date-time">
  Timestamp when the chat was last updated
</ResponseField>

<ResponseField name="last_message_at" type="string | null" format="date-time">
  Timestamp of the last message in this chat
</ResponseField>

<ResponseField name="message_count" type="integer">
  Total number of messages in this chat
</ResponseField>

<ResponseExample>
  ```json Status: 200 OK theme={null}
  {
    "chats": [
      {
        "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "user_id": "user123",
        "tenant_id": "tenant-uuid-here",
        "title": "Support Session",
        "config": {
          "metadata": {
            "department": "technical",
            "priority": "high"
          }
        },
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:35:00Z",
        "last_message_at": "2024-01-15T10:35:00Z",
        "message_count": 5
      },
      {
        "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
        "user_id": "user123",
        "tenant_id": "tenant-uuid-here",
        "title": "Billing Question",
        "config": {
          "metadata": {
            "department": "billing",
            "priority": "low"
          }
        },
        "created_at": "2024-01-14T15:20:00Z",
        "updated_at": "2024-01-14T15:45:00Z",
        "last_message_at": "2024-01-14T15:45:00Z",
        "message_count": 8
      }
    ],
    "total": 15,
    "offset": 0,
    "limit": 50,
    "has_more": false
  }
  ```
</ResponseExample>

## Error Responses

<Accordion title="400: Bad Request">
  Invalid query parameters
</Accordion>

<Accordion title="401: Unauthorized">
  Invalid or missing API key
</Accordion>

<Accordion title="404: Not Found">
  User not found or no chats exist for this user
</Accordion>

<Accordion title="500: Internal Server Error">
  Server error processing the request
</Accordion>

## Example Usage

### cURL

```bash theme={null}
curl -X GET "http://localhost:8000/api/v1/chats/user/user123?limit=10&offset=0&order=desc" \
  -H "X-API-Key: your-tenant-api-key"
```

### JavaScript

```javascript theme={null}
const userId = 'user123';
const params = new URLSearchParams({
  limit: '10',
  offset: '0',
  order: 'desc'
});

fetch(`http://localhost:8000/api/v1/chats/user/${userId}?${params}`, {
  method: 'GET',
  headers: {
    'X-API-Key': 'your-tenant-api-key'
  }
})
.then(response => response.json())
.then(data => {
  console.log(`Found ${data.total} chats for user`);
  data.chats.forEach(chat => {
    console.log(`Chat: ${chat.title} (${chat.message_count} messages)`);
  });
})
.catch(error => console.error('Error:', error));
```

### Python

```python theme={null}
import requests

user_id = "user123"
url = f"http://localhost:8000/api/v1/chats/user/{user_id}"
headers = {"X-API-Key": "your-tenant-api-key"}
params = {
    "limit": 10,
    "offset": 0,
    "order": "desc"
}

response = requests.get(url, headers=headers, params=params)
data = response.json()

print(f"Found {data['total']} chats for user {user_id}")
for chat in data['chats']:
    print(f"Chat: {chat['title']} ({chat['message_count']} messages)")
```

## Notes

* Results are automatically filtered to only include chats belonging to your tenant
* The `order` parameter sorts chats by their `created_at` timestamp
* `last_message_at` will be `null` for chats with no messages
* `message_count` provides a quick way to see chat activity without fetching all messages
* Use pagination for users with many chats to improve performance