List Messages

Retrieves messages from a chat session with support for pagination, filtering, and sorting. This endpoint is essential for displaying conversation history and implementing real-time chat interfaces.

Endpoint

GET https://api.nexusgpt.io/api/public/thread/{id}/messages

Authentication

api-key

string

required

Your Nexus API key for authentication

Path Parameters

string

required

The session ID to retrieve messages from

Query Parameters

limit

number

default:"20"

Number of messages to return (1-100)

order

string

default:"asc"

Sort order for messages

asc - Oldest messages first (chronological)
desc - Newest messages first (reverse chronological)

after

string

Cursor for pagination. Returns messages after this message ID.

before

string

Cursor for pagination. Returns messages before this message ID.

[
  {
    "id": "msg_001",
    "type": "user",
    "content": "Hello, I need help with my order",
    "createdAt": "2024-01-20T10:30:00Z"
  },
  {
    "id": "msg_002",
    "type": "assistant",
    "content": "I'd be happy to help you with your order! Could you please provide your order number?",
    "createdAt": "2024-01-20T10:30:05Z",
    "metadata": {
      "processingTime": 1.2,
      "modelUsed": "gpt-4"
    }
  },
  {
    "id": "msg_003",
    "type": "user",
    "content": "Sure, it's #12345",
    "createdAt": "2024-01-20T10:30:30Z"
  },
  {
    "id": "msg_004",
    "type": "tool",
    "content": "Order #12345 found: Status - Shipped, Tracking: 1Z999AA1012345678",
    "toolCallId": "call_abc123",
    "createdAt": "2024-01-20T10:30:32Z"
  },
  {
    "id": "msg_005",
    "type": "assistant",
    "content": "Great! I found your order #12345. It has been shipped and is currently in transit. Your tracking number is 1Z999AA1012345678.",
    "createdAt": "2024-01-20T10:30:35Z"
  }
]

Response Fields

Array

Message[]

required

Array of message objects

Show Message object properties

string

required

Unique identifier for the message

type

string

required

Type of message:

user - Message from the user
assistant - Response from the AI agent
tool - Result from a tool execution
system - System notification

content

string

required

The message content

createdAt

string

required

ISO 8601 timestamp of when the message was created

toolCallId

string

For tool messages, the ID of the tool call

metadata

object

Additional message metadata (varies by message type)

Example Usage

# Get latest 10 messages
curl -X GET "https://api.nexusgpt.io/api/public/thread/550e8400-e29b-41d4-a716-446655440000/messages?limit=10&order=desc" \
  -H "api-key: YOUR_API_KEY"

# Get messages with pagination
curl -X GET "https://api.nexusgpt.io/api/public/thread/550e8400-e29b-41d4-a716-446655440000/messages?limit=20&after=msg_100" \
  -H "api-key: YOUR_API_KEY"

Pagination Patterns

Forward Pagination

// Get messages page by page moving forward
async function forwardPagination(sessionId) {
  let messages = [];
  let after = null;
  
  do {
    const page = await getMessages(sessionId, {
      limit: 20,
      order: 'asc',
      after
    });
    
    messages = messages.concat(page);
    after = page.length > 0 ? page[page.length - 1].id : null;
    
  } while (after && messages.length < 100); // Stop at 100 messages
  
  return messages;
}

Backward Pagination

// Get newest messages first
async function backwardPagination(sessionId) {
  let messages = [];
  let before = null;
  
  do {
    const page = await getMessages(sessionId, {
      limit: 20,
      order: 'desc',
      before
    });
    
    messages = page.concat(messages); // Prepend to maintain order
    before = page.length > 0 ? page[page.length - 1].id : null;
    
  } while (before);
  
  return messages;
}

Real-time Polling

// Poll for new messages
async function pollForNewMessages(sessionId, onNewMessage) {
  let lastMessageId = null;
  
  // Get initial messages
  const initial = await getMessages(sessionId, { limit: 10, order: 'desc' });
  if (initial.length > 0) {
    lastMessageId = initial[0].id;
  }
  
  // Poll for new messages
  setInterval(async () => {
    if (!lastMessageId) return;
    
    const newMessages = await getMessages(sessionId, {
      order: 'asc',
      after: lastMessageId
    });
    
    if (newMessages.length > 0) {
      lastMessageId = newMessages[newMessages.length - 1].id;
      newMessages.forEach(onNewMessage);
    }
  }, 2000); // Poll every 2 seconds
}

Message Types

User Messages

{
  "id": "msg_user_001",
  "type": "user",
  "content": "What's the weather like today?",
  "createdAt": "2024-01-20T10:30:00Z"
}

Assistant Messages

{
  "id": "msg_asst_001",
  "type": "assistant",
  "content": "I'd be happy to help you with weather information...",
  "createdAt": "2024-01-20T10:30:05Z",
  "metadata": {
    "processingTime": 1.5,
    "tokensUsed": 150
  }
}

Tool Messages

{
  "id": "msg_tool_001",
  "type": "tool",
  "content": "Current weather: 72°F, Sunny",
  "toolCallId": "call_weather_api",
  "createdAt": "2024-01-20T10:30:03Z"
}

System Messages

{
  "id": "msg_sys_001",
  "type": "system",
  "content": "Session started",
  "createdAt": "2024-01-20T10:29:00Z"
}

Error Responses

{
  "statusCode": 404,
  "message": "Session not found",
  "error": "Not Found"
}

Best Practices

Efficient Pagination

Use cursors (after/before) instead of offset-based pagination
Request only as many messages as needed
Cache messages client-side to reduce API calls
Use appropriate page sizes (20-50 messages)

Real-time Updates

Implement exponential backoff for polling
Track the latest message ID to fetch only new messages
Handle duplicate messages gracefully

Message Rendering

Sanitize message content before displaying
Handle different message types appropriately
Show loading states during message fetching
Implement virtual scrolling for large conversations

Performance

Fetch messages in batches
Implement lazy loading for conversation history
Use descending order for recent messages
Minimize API calls with smart caching

Send Message - Send new messages to the session
Get Session - Get session information
Create Session - Create a new chat session

Overview

Endpoints

List Messages

List Messages

Endpoint

Authentication

Path Parameters

Query Parameters

Response Fields

Example Usage

Real-time Polling

Message Types

User Messages

Assistant Messages

Tool Messages

System Messages

Error Responses

Best Practices

Overview

Endpoints

​List Messages

​Endpoint

​Authentication

​Path Parameters

​Query Parameters

​Response Fields

​Example Usage

​Pagination Patterns

​Forward Pagination

​Backward Pagination

​Real-time Polling

​Message Types

​User Messages

​Assistant Messages

​Tool Messages

​System Messages

​Error Responses

​Best Practices

​Related Endpoints

List Messages

Endpoint

Authentication

Path Parameters

Query Parameters

Response Fields

Example Usage

Pagination Patterns

Forward Pagination

Backward Pagination

Real-time Polling

Message Types

User Messages

Assistant Messages

Tool Messages

System Messages

Error Responses

Best Practices

Related Endpoints