Get Chat History by Agent

Retrieve conversation history for a specific AI agent.

Endpoint

GET /api/v1/chat-history/agent/{agentId}

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 messages to return per page (max: 100)
`thread_id`	string	No	-	Filter by specific thread/conversation ID
`start_date`	string (ISO 8601)	No	-	Filter messages from this date onwards
`end_date`	string (ISO 8601)	No	-	Filter messages up to this date

Response

Success Response

Status Code: 200 OK

Response Body:

{
  "success": true,
  "data": {
    "messages": [
      {
        "id": "440e8400-e29b-41d4-a716-446655440099",
        "agent_id": "550e8400-e29b-41d4-a716-446655440000",
        "thread_id": "thread_abc123xyz",
        "input": "What are your business hours?",
        "output": "Our business hours are Monday to Friday, 9 AM to 6 PM EST.",
        "input_tokens": 8,
        "output_tokens": 15,
        "total_credits": 3,
        "created_at": "2024-01-20T14:30:00Z",
        "channel": "API"
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440088",
        "agent_id": "550e8400-e29b-41d4-a716-446655440000",
        "thread_id": "thread_abc123xyz",
        "input": "Do you offer technical support?",
        "output": "Yes, we offer 24/7 technical support for all our customers. You can reach us via email, phone, or live chat.",
        "input_tokens": 7,
        "output_tokens": 22,
        "total_credits": 3,
        "created_at": "2024-01-20T14:32:15Z",
        "channel": "API"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 2,
      "has_more": false
    }
  }
}

Response Fields

Field	Type	Description
`success`	boolean	Indicates if the request was successful
`data.messages`	array	Array of message objects
`data.messages[].id`	string (UUID)	Unique identifier for the message
`data.messages[].agent_id`	string (UUID)	ID of the agent that processed the message
`data.messages[].thread_id`	string	Conversation thread identifier
`data.messages[].input`	string	User's input message
`data.messages[].output`	string	Agent's response message
`data.messages[].input_tokens`	integer	Number of tokens in the input
`data.messages[].output_tokens`	integer	Number of tokens in the output
`data.messages[].total_credits`	integer	Total credits consumed for this message
`data.messages[].created_at`	string (ISO 8601)	Timestamp when the message was created
`data.messages[].channel`	string	Channel where the message originated (API, WEB, WHATSAPP)
`data.pagination`	object	Pagination information
`data.pagination.page`	integer	Current page number
`data.pagination.limit`	integer	Number of items per page
`data.pagination.total`	integer	Total number of messages
`data.pagination.has_more`	boolean	Whether there are more pages available

Error Responses

401 Unauthorized

Missing or Invalid API Key:

Status: 401 Unauthorized
{
  "success": false,
  "error": "Invalid or missing API key"
}

403 Forbidden

Agent Not in Organization:

Status: 403 Forbidden
{
  "success": false,
  "error": "Agent does not belong to your organization"
}

404 Not Found

Agent Not Found:

Status: 404 Not Found
{
  "success": false,
  "error": "Agent not found"
}

400 Bad Request

Invalid Parameters:

Status: 400 Bad Request
{
  "success": false,
  "error": "Invalid page or limit parameter"
}

500 Internal Server Error

Status: 500 Internal Server Error
{
  "success": false,
  "error": "Internal server error"
}

Example Usage

cURL

# Get first page of chat history
curl -X GET "https://agentsgt.com/api/v1/chat-history/agent/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer pk_1234567890abcdef:sk_abcdef1234567890"

# Get chat history with pagination
curl -X GET "https://agentsgt.com/api/v1/chat-history/agent/550e8400-e29b-41d4-a716-446655440000?page=2&limit=25" \
  -H "Authorization: Bearer pk_1234567890abcdef:sk_abcdef1234567890"

# Filter by thread ID
curl -X GET "https://agentsgt.com/api/v1/chat-history/agent/550e8400-e29b-41d4-a716-446655440000?thread_id=thread_abc123xyz" \
  -H "Authorization: Bearer pk_1234567890abcdef:sk_abcdef1234567890"

# Filter by date range
curl -X GET "https://agentsgt.com/api/v1/chat-history/agent/550e8400-e29b-41d4-a716-446655440000?start_date=2024-01-01T00:00:00Z&end_date=2024-01-31T23:59:59Z" \
  -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';

// Basic request
fetch(`https://agentsgt.com/api/v1/chat-history/agent/${agentId}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${publicKey}:${secretKey}`,
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(data => {
    console.log(`Found ${data.data.messages.length} messages`);
    data.data.messages.forEach(msg => {
      console.log(`[${msg.created_at}] User: ${msg.input}`);
      console.log(`[${msg.created_at}] Agent: ${msg.output}`);
    });
  })
  .catch(error => {
    console.error('Error:', error);
  });

// With pagination and filters
const params = new URLSearchParams({
  page: '1',
  limit: '25',
  thread_id: 'thread_abc123xyz'
});

fetch(`https://agentsgt.com/api/v1/chat-history/agent/${agentId}?${params}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${publicKey}:${secretKey}`,
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(data => {
    console.log('Chat history:', data.data.messages);
    console.log('Has more:', data.data.pagination.has_more);
  });

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'
}

# Basic request
response = requests.get(
    f'https://agentsgt.com/api/v1/chat-history/agent/{agent_id}',
    headers=headers
)

if response.status_code == 200:
    data = response.json()
    print(f"Found {len(data['data']['messages'])} messages")

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

# With filters
params = {
    'page': 1,
    'limit': 25,
    'thread_id': 'thread_abc123xyz',
    'start_date': '2024-01-01T00:00:00Z',
    'end_date': '2024-01-31T23:59:59Z'
}

response = requests.get(
    f'https://agentsgt.com/api/v1/chat-history/agent/{agent_id}',
    headers=headers,
    params=params
)

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/chat-history/agent/${agentId}`, {
  headers: {
    'Authorization': `Bearer ${publicKey}:${secretKey}`,
    'Content-Type': 'application/json'
  },
  params: {
    page: 1,
    limit: 50,
    thread_id: 'thread_abc123xyz'
  }
})
  .then(response => {
    const { messages, pagination } = response.data.data;

    console.log(`Page ${pagination.page} of chat history`);
    console.log(`Total messages: ${pagination.total}`);

    messages.forEach(msg => {
      console.log(`\nThread: ${msg.thread_id}`);
      console.log(`User: ${msg.input}`);
      console.log(`Agent: ${msg.output}`);
    });

    if (pagination.has_more) {
      console.log('\nMore messages available on next page');
    }
  })
  .catch(error => {
    console.error('Error:', error.response?.data || error.message);
  });

Notes

Messages are returned in ascending order by creation date (oldest first)
Maximum limit is 100 messages per page
The thread_id represents a unique conversation session
All messages must belong to agents in your organization
Date filters use ISO 8601 format with timezone information
The API key's last_used_at timestamp is automatically updated when this endpoint is called

Get Chat History by Identifier - Retrieve chat history for a specific user/session identifier
Get All Agents - List all agents in your organization

Endpoint​

Authentication​

Request​

Path Parameters​

Headers​

Query Parameters​

Response​

Success Response​

Response Fields​

Error Responses​

401 Unauthorized​

403 Forbidden​

404 Not Found​

400 Bad Request​

500 Internal Server Error​

Example Usage​

cURL​

JavaScript (Fetch API)​

Python (Requests)​

Node.js (Axios)​

Notes​

Related Endpoints​