Sessions API
Create, retrieve, and manage agent execution sessions.
Base URL
https://api.realm.ai/v1
Create Session
Create a new tracking session for your agent execution.
POST
/sessionsRequest Body
{
"name": "Customer Support Agent",
"metadata": {
"user_id": "user_123",
"environment": "production"
}
}Response
{
"id": "session_abc123",
"name": "Customer Support Agent",
"status": "active",
"created_at": "2025-11-29T10:00:00Z",
"metadata": {
"user_id": "user_123",
"environment": "production"
}
}cURL Example
curl -X POST https://api.realm.ai/v1/sessions \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{
"name": "Customer Support Agent",
"metadata": {
"user_id": "user_123"
}
}'Get Session
Retrieve details about a specific session.
GET
/sessions/:idResponse
{
"id": "session_abc123",
"name": "Customer Support Agent",
"status": "completed",
"created_at": "2025-11-29T10:00:00Z",
"completed_at": "2025-11-29T10:05:23Z",
"metadata": {
"user_id": "user_123",
"environment": "production"
},
"stats": {
"total_events": 45,
"tool_calls": 12,
"decisions": 8,
"llm_calls": 10,
"errors": 0,
"duration_ms": 323000
}
}cURL Example
curl https://api.realm.ai/v1/sessions/session_abc123 \
-H "Authorization: Bearer your-api-key"List Sessions
Retrieve a list of sessions with optional filtering.
GET
/sessionsQuery Parameters
| Parameter | Type | Description |
|---|---|---|
| limit | integer | Max results (default: 50, max: 100) |
| offset | integer | Pagination offset |
| status | string | Filter by status: active, completed, error |
| created_after | ISO 8601 | Filter sessions created after date |
Response
{
"sessions": [
{
"id": "session_abc123",
"name": "Customer Support Agent",
"status": "completed",
"created_at": "2025-11-29T10:00:00Z"
},
...
],
"total": 156,
"has_more": true
}Update Session
Update session metadata or close a session.
PATCH
/sessions/:idRequest Body
{
"status": "completed",
"metadata": {
"final_result": "success",
"user_satisfaction": "high"
}
}Get Session Events
Retrieve all events for a session.
GET
/sessions/:id/eventsResponse
{
"events": [
{
"id": "event_123",
"type": "tool_call",
"timestamp": "2025-11-29T10:01:23Z",
"data": {
"tool_name": "search_kb",
"tool_input": {...},
"tool_output": {...}
}
},
...
],
"total": 45
}