Get Thread Messages

Retrieve all messages from a specific conversation thread. Messages are returned in chronological order (oldest first).

Endpoint

GET /api/v1/agents/{agentId}/threads/{threadId}

Authentication

This endpoint requires API key authentication. Include your API key in the Authorization header using the Bearer scheme.

Header Format:

Authorization: Bearer {PUBLIC_KEY}:{SECRET_KEY}

Request

Path Parameters

Parameter	Type	Required	Description
agentId	string (UUID)	Yes	The unique identifier of the agent
threadId	string	Yes	The unique identifier of the conversation thread

Headers

Header	Type	Required	Description
Authorization	string	Yes	Your API key in the format Bearer pk_xxx:sk_xxx

Query Parameters

Parameter	Type	Required	Default	Description
page	integer	No	1	Page number for pagination
limit	integer	No	100	Number of messages per page (max: 100)

Response

Success Response

Status Code: 200 OK

Response Body:

{
  "thread_id": "thread_abc123xyz",
  "identifier": "user-123",
  "messages": [
    {
      "id": "msg-001",
      "agent_id": "550e8400-e29b-41d4-a716-446655440000",
      "thread_id": "thread_abc123xyz",
      "organization_id": "org-001",
      "input": "What products do you offer?",
      "output": "We offer a wide range of products including...",
      "input_tokens": 7,
      "output_tokens": 45,
      "total_credits": 3,
      "channel": "API",
      "created_at": "2024-01-20T14:30:00Z"
    },
    {
      "id": "msg-002",
      "agent_id": "550e8400-e29b-41d4-a716-446655440000",
      "thread_id": "thread_abc123xyz",
      "organization_id": "org-001",
      "input": "What about pricing?",
      "output": "Our pricing starts at $9.99 per month...",
      "input_tokens": 5,
      "output_tokens": 32,
      "total_credits": 3,
      "channel": "API",
      "created_at": "2024-01-20T14:31:15Z"
    }
  ],
  "total": 2,
  "page": 1,
  "limit": 100
}

Response Fields

Field	Type	Description
thread_id	string	The conversation thread ID
identifier	string | null	External user identifier (if mapped)
messages	array	Array of message objects in chronological order
messages[].id	string	Unique identifier for the message
messages[].agent_id	string	ID of the agent that processed the message
messages[].thread_id	string	Conversation thread identifier
messages[].organization_id	string	Organization that owns the agent
messages[].input	string	User's input message
messages[].output	string	Agent's response message
messages[].input_tokens	integer	Number of tokens in the input
messages[].output_tokens	integer	Number of tokens in the output
messages[].total_credits	integer	Credits consumed for this message
messages[].channel	string	Message channel (API, WEB, WHATSAPP, INSTAGRAM)
messages[].created_at	string (ISO 8601)	Timestamp when the message was created
total	number	Total number of messages in this thread
page	number	Current page number
limit	number	Number of items per page

Error Responses

401 Unauthorized

{
  "error": "Unauthorized"
}

404 Not Found

{
  "error": "Agent not found"
}

500 Internal Server Error

{
  "error": "Internal server error"
}

Example Usage

cURL

curl -X GET https://agentsgt.com/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/threads/thread_abc123xyz \
  -H "Authorization: Bearer pk_1234567890abcdef:sk_abcdef1234567890"

JavaScript (Fetch API)

const publicKey = 'pk_1234567890abcdef';
const secretKey = 'sk_abcdef1234567890';
const agentId = '550e8400-e29b-41d4-a716-446655440000';
const threadId = 'thread_abc123xyz';

fetch(`https://agentsgt.com/api/v1/agents/${agentId}/threads/${threadId}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${publicKey}:${secretKey}`,
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(data => {
    console.log(`Thread: ${data.thread_id}`);
    console.log(`User: ${data.identifier || 'Anonymous'}`);
    console.log(`Messages: ${data.total}`);

    data.messages.forEach(msg => {
      console.log(`\n[${msg.created_at}]`);
      console.log(`User: ${msg.input}`);
      console.log(`Agent: ${msg.output}`);
    });
  })
  .catch(error => {
    console.error('Error:', error);
  });

Python (Requests)

import requests

public_key = 'pk_1234567890abcdef'
secret_key = 'sk_abcdef1234567890'
agent_id = '550e8400-e29b-41d4-a716-446655440000'
thread_id = 'thread_abc123xyz'

headers = {
    'Authorization': f'Bearer {public_key}:{secret_key}',
    'Content-Type': 'application/json'
}

response = requests.get(
    f'https://agentsgt.com/api/v1/agents/{agent_id}/threads/{thread_id}',
    headers=headers
)

if response.status_code == 200:
    data = response.json()
    print(f"Thread: {data['thread_id']}")
    print(f"User: {data['identifier'] or 'Anonymous'}")
    print(f"Total messages: {data['total']}")

    for msg in data['messages']:
        print(f"\n[{msg['created_at']}]")
        print(f"User: {msg['input']}")
        print(f"Agent: {msg['output']}")
        print(f"Credits: {msg['total_credits']}")
else:
    print(f"Error: {response.status_code} - {response.json()}")

Node.js (Axios)

const axios = require('axios');

const publicKey = 'pk_1234567890abcdef';
const secretKey = 'sk_abcdef1234567890';
const agentId = '550e8400-e29b-41d4-a716-446655440000';
const threadId = 'thread_abc123xyz';

axios.get(`https://agentsgt.com/api/v1/agents/${agentId}/threads/${threadId}`, {
  headers: {
    'Authorization': `Bearer ${publicKey}:${secretKey}`,
    'Content-Type': 'application/json'
  }
})
  .then(response => {
    const { thread_id, identifier, messages, total } = response.data;
    console.log(`Thread ${thread_id} - ${total} messages`);
    messages.forEach(msg => {
      console.log(`[${msg.channel}] ${msg.input} -> ${msg.output.substring(0, 50)}...`);
    });
  })
  .catch(error => {
    console.error('Error:', error.response?.data || error.message);
  });

Notes

• Messages are returned in ascending chronological order (oldest first)
• The identifier field is resolved from the thread_mappings table
• Maximum limit is 100 messages per page
• The channel field shows where the conversation originated (API, WEB, WHATSAPP, or INSTAGRAM)
• Use the List Threads endpoint first to get available thread IDs

Related Endpoints

• List Threads - Get all threads for an agent
• Get Chat History by Agent - Alternative way to browse chat history
• Get Chat History by Identifier - Get history for a specific user