Log and retrieve conversation interactions between users and agents
POST /v1/sessions/{session_id}/turns
Logs a new conversation turn. This is typically called after your agent generates a response.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | ✅ Yes | Session ID to add turn to |
| Field | Type | Required | Description |
|---|---|---|---|
input | object | ✅ Yes | User’s input (see Input Object below) |
output | object | ✅ Yes | Agent’s response (see Output Object below) |
reasoning | string | No | Why the agent made this decision (for debugging) |
metadata | object | No | Custom data (e.g., {"tool_used": "weather_api", "latency_ms": 450}) |
state_before | object | No | Session state before this turn |
state_after | object | No | Session state after this turn |
| Field | Type | Required | Description |
|---|---|---|---|
type | string | ✅ Yes | Content type: "text", "audio", "image", "tool_call" |
content | string | ✅ Yes | The actual input content |
| Field | Type | Required | Description |
|---|---|---|---|
type | string | ✅ Yes | Content type: "text", "audio", "image", "tool_result", "error" |
content | string | ✅ Yes | The actual output content |
| Field | Type | Description |
|---|---|---|
id | string | Unique turn ID (format: turn_<12_chars>) |
session_id | string | Parent session ID |
turn_number | integer | Sequential turn number (starts at 1) |
created_at | string | ISO 8601 timestamp |
input | object | User input |
output | object | Agent output |
reasoning | string | Agent’s reasoning (if provided) |
metadata | object | Custom metadata |
state_before | object | State snapshot before turn |
state_after | object | State snapshot after turn |
GET /v1/sessions/{session_id}/turns/{turn_id}
Retrieves a specific turn by ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | ✅ Yes | Session ID |
turn_id | string | ✅ Yes | Turn ID |
GET /v1/sessions/{session_id}/turns
Lists all turns for a session, ordered by creation time (newest first).
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | ✅ Yes | Session ID |
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | integer | No | Max turns to return (default: 20, max: 100) |
starting_after | string | No | Turn ID to start after (for pagination) |
order | string | No | Sort order: "asc" or "desc" (default: "desc") |
reasoning (invaluable for debugging)"text", "tool_call", "error")| Type | Description | Example |
|---|---|---|
text | Plain text input | "What's the weather?" |
audio | Audio transcription | "[Audio: 5.2s]" |
image | Image description | "[Image: screenshot.png]" |
tool_call | Tool invocation | "get_weather(city='SF')" |
| Type | Description | Example |
|---|---|---|
text | Plain text response | "It's 72°F and sunny" |
audio | Audio response | "[Audio: response.mp3]" |
image | Generated image | "[Image: chart.png]" |
tool_result | Tool output | {"temp": 72, "condition": "sunny"} |
error | Error message | "API timeout after 5s" |
| Status Code | Error Code | Description |
|---|---|---|
| 400 | invalid_request | Missing required fields |
| 404 | session_not_found | Session doesn’t exist |
| 404 | turn_not_found | Turn doesn’t exist |
| 429 | rate_limit_exceeded | Too many requests |