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