Get Chat History

Endpoint

GET /chat/history
Base URL: https://api.example-ai.com/v1

Description

Retrieve the message history for a specific conversation.
Use this endpoint to paginate through chat messages between a user and the AI or between multiple participants. This is typically used to render past messages in a client application.

Authentication

This endpoint requires Bearer Token authentication:

Authorization: Bearer sk_test_51_fakeapikey123456

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer <token>
Content-Type	string	No	application/json (for consistency)
X-Request-Id	string	No	Optional client-supplied request identifier.

Request Parameters

Query Parameters

Name	Type	Required	Description
conversation_id	string	Yes	Unique ID of the conversation, e.g. con_9s2kd81.
limit	integer	No	Max number of messages to return per page. Default: 20. Max: 100.
before	string	No	Return messages created before this ISO timestamp. Used for backward paging.
after	string	No	Return messages created after this ISO timestamp. Used for forward paging.
include_meta	boolean	No	If true, includes extended metadata for each message. Default: false.

before and after are mutually exclusive; only one should be provided.

Example Request

curl

curl -X GET "https://api.example-ai.com/v1/chat/history?conversation_id=con_9s2kd81&limit=20&before=2026-03-15T14:22:11Z" \
  -H "Authorization: Bearer sk_test_51_fakeapikey123456" \
  -H "Content-Type: application/json"

Example Response

{
  "status": "success",
  "message": "Chat history retrieved successfully.",
  "data": {
    "conversation_id": "con_9s2kd81",
    "messages": [
      {
        "id": "msg_92kd82",
        "sender_type": "user",
        "sender_id": "usr_82hd92",
        "text": "Hey, can you summarize today's calls?",
        "metadata": {
          "channel": "web",
          "attachments": []
        },
        "created_at": "2026-03-15T13:59:11Z"
      },
      {
        "id": "msg_18dk03",
        "sender_type": "ai",
        "sender_id": "ai_default_bot",
        "text": "Sure, you had 12 inbound and 5 outbound calls today.",
        "metadata": {
          "model": "gpt-4o-mini",
          "latency_ms": 743
        },
        "created_at": "2026-03-15T14:00:01Z"
      }
    ]
  },
  "pagination": {
    "limit": 20,
    "next_cursor": "2026-03-15T13:30:00Z",
    "has_more": true
  }
}

Error Responses

400 Bad Request

{
  "status": "error",
  "message": "Invalid query parameter: before and after cannot both be set.",
  "data": null
}

401 Unauthorized

{
  "status": "error",
  "message": "Missing or invalid Authorization header.",
  "data": null
}

404 Not Found

{
  "status": "error",
  "message": "Conversation not found: con_9s2kd81.",
  "data": null
}

500 Server Error

{
  "status": "error",
  "message": "Unexpected server error. Please try again later.",
  "data": null
}

Code Examples

curl

curl -X GET "https://api.example-ai.com/v1/chat/history?conversation_id=con_9s2kd81&limit=50" \
  -H "Authorization: Bearer sk_test_51_fakeapikey123456" \
  -H "Content-Type: application/json"

JavaScript (fetch)

const params = new URLSearchParams({
  conversation_id: 'con_9s2kd81',
  limit: '50',
})

const response = await fetch(`https://api.example-ai.com/v1/chat/history?${params.toString()}`, {
  method: 'GET',
  headers: {
    Authorization: 'Bearer sk_test_51_fakeapikey123456',
    'Content-Type': 'application/json',
  },
})

const result = await response.json()
console.log(result.data.messages)

TypeScript (axios)

import axios, { AxiosResponse } from 'axios'

interface ChatMessage {
  id: string
  sender_type: 'user' | 'ai' | 'system'
  sender_id: string
  text: string
  metadata?: Record<string, unknown>
  created_at: string
}

interface ChatHistoryResponse {
  status: 'success' | 'error'
  message: string
  data: {
    conversation_id: string
    messages: ChatMessage[]
  } | null
  pagination?: {
    limit: number
    next_cursor?: string
    has_more: boolean
  }
}

const res: AxiosResponse<ChatHistoryResponse> = await axios.get(
  'https://api.example-ai.com/v1/chat/history',
  {
    headers: {
      Authorization: 'Bearer sk_test_51_fakeapikey123456',
    },
    params: {
      conversation_id: 'con_9s2kd81',
      limit: 50,
    },
  },
)

console.log(res.data.data?.messages)

Notes

• Use cursors (before or after) instead of page numbers for stable pagination over time.
• The message list is returned in descending chronological order by default (newest first).
• Timestamps are always in UTC and ISO 8601 format.