Thread Messages: List v1

The List Messages API allows you to retrieve all messages in a thread. This is essential for accessing complete conversation history and building interfaces that display past interactions.

Note

Messages are returned in chronological order with the oldest messages appearing first in the array. This makes it easy to reconstruct the conversation flow as it occurred.

The List Messages API provides:

  • Complete conversation history for a specific thread
  • Chronological ordering of messages
  • Access to message metadata and attachments

GET/v1/threads/{threadId}/messages

List messages in a thread

Retrieve all messages in a specific thread.

Headers

  • Name
    Authorization
    Type
    string
    Required
    Required
    Description

    Replace LANGBASE_API_KEY with your User/Org API key


Path Parameters

  • Name
    threadId
    Type
    string
    Required
    Required
    Description

    The unique identifier of the thread to retrieve messages from.

Usage example

Install the SDK

npm i langbase

Environment variables

.env file

LANGBASE_API_KEY="<USER/ORG-API-KEY>"

List messages in a thread

List all messages

GET
/v1/threads/{threadId}/messages
import { Langbase } from 'langbase';

const langbase = new Langbase({
  apiKey: process.env.LANGBASE_API_KEY // Your User/Org API key
});

async function listMessages() {
  const threadId = "thread_abc123xyz456";
  const messages = await langbase.threads.messages.list({
    threadId: threadId
  });

  console.log(`Retrieved ${messages.length} messages from thread`);
  return messages;
}

listMessages();

Response

The response is an array of ThreadMessagesBaseResponse objects representing all messages in the thread.

  • Name
    id
    Type
    string
    Description

    The unique identifier for the message.

  • Name
    thread_id
    Type
    string
    Description

    The ID of the thread that this message belongs to.

  • Name
    created_at
    Type
    number
    Description

    The Unix timestamp (in seconds) for when the message was created.

  • Name
    role
    Type
    string
    Description

    The role of the message author. One of 'user', 'assistant', 'system', or 'tool'.

  • Name
    content
    Type
    string | null
    Description

    The content of the message. Will be null for messages that only contain tool calls.

  • Name
    tool_call_id
    Type
    string | null
    Description

    If the message is a tool response, this is the ID of the tool call it is responding to.

  • Name
    tool_calls
    Type
    Array<ToolCall> | []
    Description

    If the message contains tool calls, this array will contain the tools called by the assistant.

  • Name
    name
    Type
    string | null
    Description

    If the message is a tool response, this is the name of the tool that was called.

  • Name
    attachments
    Type
    Array<any> | []
    Description

    Any attachments associated with the message.

  • Name
    metadata
    Type
    Record<string, string> | {}
    Description

    Key-value pairs of metadata associated with the message.

Response Example

[
 {
   "id": "msg_abc123",
   "thread_id": "thread_abc123xyz456",
   "created_at": 1714322048,
   "role": "system",
   "content": "You are a helpful assistant that provides concise responses.",
   "tool_call_id": null,
   "tool_calls": [],
   "name": null,
   "attachments": [],
   "metadata": {}
 },
 {
   "id": "msg_def456",
   "thread_id": "thread_abc123xyz456",
   "created_at": 1714322148,
   "role": "user",
   "content": "Can you help me track my order?",
   "tool_call_id": null,
   "tool_calls": [],
   "name": null,
   "attachments": [],
   "metadata": {
     "userId": "user123",
     "source": "mobile_app"
   }
 },
 {
   "id": "msg_ghi789",
   "thread_id": "thread_abc123xyz456",
   "created_at": 1714322248,
   "role": "assistant",
   "content": null,
   "tool_call_id": null,
   "tool_calls": [
     {
       "id": "call_abc123",
       "type": "function",
       "function": {
         "name": "track_order",
         "arguments": "{\"order_id\":\"ORD-12345\"}"
       }
     }
   ],
   "name": null,
   "attachments": [],
   "metadata": {}
 },
 {
   "id": "msg_jkl012",
   "thread_id": "thread_abc123xyz456",
   "created_at": 1714322348,
   "role": "tool",
   "content": "{\"status\":\"shipped\",\"estimated_delivery\":\"2025-05-01\",\"carrier\":\"FedEx\",\"tracking_number\":\"TRK123456789\"}",
   "tool_call_id": "call_abc123",
   "tool_calls": [],
   "name": "track_order",
   "attachments": [],
   "metadata": {}
 },
 {
   "id": "msg_mno345",
   "thread_id": "thread_abc123xyz456",
   "created_at": 1714322448,
   "role": "assistant",
   "content": "Your order #ORD-12345 has been shipped via FedEx and is expected to arrive on May 1, 2025. You can track it with tracking number TRK123456789.",
   "tool_call_id": null,
   "tool_calls": [],
   "name": null,
   "attachments": [],
   "metadata": {}
 }
]