Skip to main content
GET
/
api
/
v1
/
chats
/
user
/
{user_id}
List User Chats
curl --request GET \
  --url https://api.example.com/api/v1/chats/user/{user_id} \
  --header 'X-API-Key: <x-api-key>'
{
  "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
}

​
List User Chats

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

​
Authentication

​
X-API-Key
string
required
Authentication header with your tenant’s API key

​
Path Parameters

​
user_id
string
required
The ID of the user whose chats you want to retrieve

​
Query Parameters

​
offset
integer
default:"0"
The number of items to skip before starting to collect results
​
limit
integer
default:"50"
The maximum number of chats to return
​
order
string
default:"desc"
Sort order for chats by creation date. Options: ‘asc’ or ‘desc’

​
Response

​
chats
array
Array of chat objects belonging to the user
​
total
integer
Total number of chats for this user
​
offset
integer
Current offset value used for pagination
​
limit
integer
Current limit value used for pagination
​
has_more
boolean
Indicates if there are more chats available

​
Chat Object

​
id
string
Unique identifier for the chat session
​
user_id
string
The ID of the user who owns this chat
​
tenant_id
string
The tenant identifier
​
title
string
The title of the chat session
​
config
object
Configuration object containing metadata and chat settings
​
created_at
string
Timestamp when the chat was created
​
updated_at
string
Timestamp when the chat was last updated
​
last_message_at
string | null
Timestamp of the last message in this chat
​
message_count
integer
Total number of messages in this chat
{
  "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
}

​
Error Responses

Invalid query parameters
Invalid or missing API key
User not found or no chats exist for this user
Server error processing the request

​
Example Usage

​
cURL

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

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

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