List Conversation Threads

Retrieve a paginated list of conversation threads for a specific agent. Each thread represents a separate conversation session with a user.

Endpoint

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

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

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	50	Number of threads per page (max: 100)

Response

Success Response

Status Code: 200 OK

Response Body:

{
  "threads": [
    {
      "thread_id": "thread_abc123xyz",
      "identifier": "user-123",
      "message_count": 24,
      "last_message_at": "2024-01-20T14:45:00Z"
    },
    {
      "thread_id": "thread_def456uvw",
      "identifier": null,
      "message_count": 8,
      "last_message_at": "2024-01-19T10:30:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 50
}

Response Fields

Field	Type	Description
threads	array	Array of thread summary objects
threads[].thread_id	string	Unique identifier for the conversation thread
threads[].identifier	string | null	External user identifier (if mapped)
threads[].message_count	number	Total number of messages in the thread
threads[].last_message_at	string (ISO 8601)	Timestamp of the most recent message
total	number	Total number of threads
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

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

# List threads with custom pagination
curl -X GET "https://agentsgt.com/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/threads?page=2&limit=25" \
  -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';

fetch(`https://agentsgt.com/api/v1/agents/${agentId}/threads?page=1&limit=25`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${publicKey}:${secretKey}`,
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(data => {
    console.log(`Total threads: ${data.total}`);
    data.threads.forEach(thread => {
      console.log(`Thread ${thread.thread_id}: ${thread.message_count} messages`);
      if (thread.identifier) {
        console.log(`  User: ${thread.identifier}`);
      }
    });
  })
  .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'

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',
    headers=headers,
    params={'page': 1, 'limit': 25}
)

if response.status_code == 200:
    data = response.json()
    print(f"Total threads: {data['total']}")
    for thread in data['threads']:
        user = thread['identifier'] or 'Anonymous'
        print(f"Thread {thread['thread_id']}: {thread['message_count']} messages (User: {user})")
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';

axios.get(`https://agentsgt.com/api/v1/agents/${agentId}/threads`, {
  headers: {
    'Authorization': `Bearer ${publicKey}:${secretKey}`,
    'Content-Type': 'application/json'
  },
  params: { page: 1, limit: 25 }
})
  .then(response => {
    const { threads, total } = response.data;
    console.log(`Total threads: ${total}`);
    threads.forEach(thread => {
      console.log(`- ${thread.thread_id}: ${thread.message_count} messages`);
    });
  })
  .catch(error => {
    console.error('Error:', error.response?.data || error.message);
  });

Notes

• Threads are aggregated from chat history using an efficient database-level query
• The identifier field is populated from the thread_mappings table when an external user identifier was provided
• Maximum limit is 100 threads per page
• Threads without an identifier may have been created through the web chat interface without user tracking
• Use thread IDs to retrieve full message history via the Get Thread Messages endpoint

Related Endpoints

• Get Thread Messages - Get all messages in a specific thread
• Get Chat History by Agent - Get chat history with filtering options
• Get Chat History by Identifier - Get chat history for a specific user