> ## Documentation Index
> Fetch the complete documentation index at: https://docs.splox.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Chat History
> Retrieves paginated chat message history. Returns a bare JSON array of messages, newest first.
Retrieves paginated chat message history for a chat session. Messages are returned newest-first.
## Usage
```bash cURL theme={null}
curl "https://app.splox.io/api/v1/chat-history/0199f200-a11b-7c8d-4444-888890abcdef/paginated?limit=20" \
-H "Authorization: Bearer YOUR_TOKEN"
```
```python Python theme={null}
from splox import SploxClient
client = SploxClient(api_key="YOUR_API_KEY")
result = client.chats.get_history("CHAT_ID", limit=20)
for msg in result.messages:
text = msg.content[0].text if msg.content else ""
print(f"[{msg.role}] {text}")
# Paginate backward
if result.has_more:
oldest = result.messages[-1].created_at
older = client.chats.get_history("CHAT_ID", limit=20, before=oldest)
```
```typescript Node.js theme={null}
import Splox from "splox";
const client = new Splox("YOUR_API_KEY");
const result = await client.chats.getHistory("CHAT_ID", { limit: 20 });
for (const msg of result.messages) {
const text = msg.content?.[0]?.text ?? "";
console.log(`[${msg.role}] ${text}`);
}
// Paginate backward
if (result.has_more) {
const oldest = result.messages.at(-1)!.created_at!;
const older = await client.chats.getHistory("CHAT_ID", { limit: 20, before: oldest });
}
```
```go Go theme={null}
client := splox.NewClient("YOUR_API_KEY")
result, err := client.Chats.GetHistory(ctx, "CHAT_ID", &splox.ChatHistoryParams{
Limit: 20,
})
for _, msg := range result.Messages {
text := ""
if len(msg.Content) > 0 {
text = msg.Content[0].Text
}
fmt.Printf("[%s] %s\n", msg.Role, text)
}
```
## Path Parameters
| Parameter | Type | Description |
| --------- | ------------- | ----------- |
| `chatId` | string (uuid) | Chat ID |
## Query Parameters
| Parameter | Type | Default | Description |
| --------- | ---------------- | ------- | -------------------------------------------------------------------------- |
| `limit` | integer | 50 | Messages per page (1–200) |
| `before` | string (RFC3339) | — | Timestamp cursor for backward pagination. Omit to get the latest messages. |
## Response
Returns a **bare JSON array** of message objects:
```json theme={null}
[
{
"id": "019c3221-29dc-7735-a4e3-b42ebb1a0cf1",
"chat_id": "0199f200-a11b-7c8d-4444-888890abcdef",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Hello! How can I help you today?"
}
],
"files": [],
"created_at": "2025-10-22T10:01:00Z",
"updated_at": "2025-10-22T10:01:00Z"
},
{
"id": "019c3221-29dc-7735-a4e3-b42ebb1a0cf2",
"chat_id": "0199f200-a11b-7c8d-4444-888890abcdef",
"role": "user",
"content": [
{
"type": "text",
"text": "Summarize the latest report"
}
],
"created_at": "2025-10-22T10:00:00Z",
"updated_at": "2025-10-22T10:00:00Z"
}
]
```
### Message Roles
| Role | Description |
| ----------- | -------------------------- |
| `user` | Message from the user |
| `assistant` | Response from the AI agent |
| `system` | System-level message |
| `tool` | Tool execution result |
### Content Types
| Type | Description |
| ------------- | -------------------------------------------- |
| `text` | Plain text content |
| `tool-call` | A tool invocation with `toolName` and `args` |
| `tool-result` | Result from a tool execution |
| `source` | Source reference with `url` and `title` |
### Pagination
Use the `created_at` timestamp of the **oldest** message in the current page as the `before` cursor for the next page:
```bash theme={null}
# First page (latest messages)
curl ".../chat-history/{chatId}/paginated?limit=20"
# Next page (older messages)
curl ".../chat-history/{chatId}/paginated?limit=20&before=2025-10-22T10:00:00Z"
```
## Notes
**Authentication required.** The authenticated user must own the chat session.
## OpenAPI
````yaml GET /chat-history/{chatId}/paginated
openapi: 3.1.0
info:
title: Splox API
description: >-
Run workflows, manage chats, receive events, and monitor execution via the
Splox API
version: 1.0.0
contact:
name: Splox Support
email: support@splox.io
url: https://community.splox.io
servers:
- url: https://app.splox.io/api/v1
description: Production API
security: []
tags:
- name: MCP
description: Discover MCP servers, manage connections, and execute MCP tools
- name: Workflows
description: List, get, and inspect workflows, versions, and nodes
- name: Workflow Requests
description: Run workflows, monitor execution, and retrieve results
- name: Events
description: Receive external events via Event Hub webhooks
- name: Chats
description: Manage chat sessions for workflow interactions
paths:
/chat-history/{chatId}/paginated:
get:
tags:
- Chats
summary: Get Chat History
description: >-
Retrieves paginated chat message history. Returns a bare JSON array of
messages, newest first.
operationId: getChatHistory
parameters:
- name: chatId
in: path
required: true
description: Chat ID
schema:
type: string
format: uuid
- name: limit
in: query
description: 'Messages per page (default: 50, max: 200)'
schema:
type: integer
default: 50
maximum: 200
- name: before
in: query
description: >-
RFC3339 timestamp cursor for backward pagination. Omit to get latest
messages.
schema:
type: string
format: date-time
responses:
'200':
description: Chat messages retrieved successfully (bare JSON array)
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ChatMessage'
security:
- bearerAuth: []
components:
schemas:
ChatMessage:
type: object
description: A single message in a chat history
properties:
id:
type: string
format: uuid
chat_id:
type: string
format: uuid
role:
type: string
enum:
- user
- assistant
- system
- tool
parent_id:
type: string
format: uuid
nullable: true
status:
type: object
nullable: true
properties:
type:
type: string
reason:
type: string
metadata:
type: object
additionalProperties: true
nullable: true
content:
type: array
items:
$ref: '#/components/schemas/ChatMessageContent'
files:
type: array
nullable: true
items:
$ref: '#/components/schemas/WorkflowRequestFile'
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
required:
- id
- chat_id
- role
- content
ChatMessageContent:
type: object
description: A single content block within a chat message
properties:
type:
type: string
enum:
- text
- tool-call
- tool-result
- source
- credential-request
description: Content block type
text:
type: string
description: Text content
toolCallId:
type: string
description: Tool call identifier
toolName:
type: string
description: Name of the tool being called
args:
type: object
additionalProperties: true
description: Tool call arguments
result:
description: Tool execution result
reasoning:
type: string
description: Model reasoning text
required:
- type
WorkflowRequestFile:
type: object
description: File attached to a workflow request
properties:
content_type:
type: string
description: MIME type of the file
url:
type: string
format: uri
description: URL to access the file
file_name:
type: string
description: Original file name
file_size:
type: integer
format: int64
description: File size in bytes
metadata:
type: object
additionalProperties: true
description: Additional file metadata
required:
- url
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
API token generated from your Splox account settings. Create tokens at
https://app.splox.io/account?tab=settings
````