Events API

Track agent events, decisions, tool calls, and more.

Base URL

https://api.realm.ai/v1

Create Event

Track an event in your agent execution.

POST/sessions/:session_id/events

Tool Call Event

{
  "type": "tool_call",
  "data": {
    "tool_name": "search_knowledge_base",
    "tool_input": {
      "query": "password reset",
      "max_results": 5
    },
    "tool_output": {
      "articles": ["KB-001", "KB-002"],
      "relevance_scores": [0.95, 0.87]
    },
    "reasoning": "User needs help with password",
    "duration_ms": 150,
    "status": "success"
  }
}

Decision Event

{
  "type": "decision",
  "data": {
    "reasoning": "User has tried KB articles. Escalating.",
    "alternatives": [
      "Try another article",
      "Ask for more info",
      "Escalate to human"
    ],
    "chosen": "Escalate to human",
    "confidence": 0.85,
    "metadata": {
      "kb_articles_tried": 3
    }
  }
}

LLM Call Event

{
  "type": "llm_call",
  "data": {
    "model": "gpt-4",
    "prompt": "Generate a professional password reset email...",
    "response": "Dear user, here's how to reset...",
    "tokens_used": 250,
    "prompt_tokens": 100,
    "completion_tokens": 150,
    "cost": 0.005,
    "duration_ms": 1200
  }
}

Error Event

{
  "type": "error",
  "data": {
    "error_type": "APIError",
    "error_message": "Knowledge base API timeout",
    "stack_trace": "Traceback (most recent call last):\n...",
    "recoverable": true,
    "recovery_action": "Retry with fallback"
  }
}

Event Types

Type	Description	Key Fields
tool_call	Agent uses a tool or function	tool_name, tool_input, tool_output
decision	Agent makes a decision	reasoning, alternatives, chosen
llm_call	LLM API call	model, prompt, response, tokens
error	Error or exception	error_type, error_message
custom	Custom event type	Any custom fields

Batch Create Events

Create multiple events in a single request for better performance.

POST/sessions/:session_id/events/batch

Request Body

{
  "events": [
    {
      "type": "decision",
      "data": {...}
    },
    {
      "type": "tool_call",
      "data": {...}
    },
    {
      "type": "llm_call",
      "data": {...}
    }
  ]
}

Response

{
  "created": 3,
  "event_ids": ["event_123", "event_124", "event_125"]
}

Get Event

Retrieve a specific event by ID.

GET/events/:id

Response

{
  "id": "event_123",
  "session_id": "session_abc123",
  "type": "tool_call",
  "timestamp": "2025-11-29T10:01:23.456Z",
  "data": {
    "tool_name": "search_kb",
    "tool_input": {...},
    "tool_output": {...},
    "duration_ms": 150,
    "status": "success"
  }
}

Best Practices

✓ DO

Use batch API for multiple events to reduce overhead
Include relevant context in event metadata
Track errors with full stack traces
Use consistent tool naming across sessions

✗ DON'T

Send PII or sensitive data in event data
Create events for every minor function call
Block your agent on event creation (use async)
Exceed rate limits by creating too many events

Next Steps

Python SDK →

Use the SDK for easier event tracking

Sessions & Events →

Learn about core concepts