Events API

POST /api/events

Ingest a batch of events. Events are validated, assigned IDs, added to the session hash chain, and persisted atomically.

Request Body

{
  "events": [
    {
      "sessionId": "01HXYZ...",
      "agentId": "my-agent",
      "eventType": "tool_call",
      "severity": "info",
      "payload": {
        "toolName": "search",
        "callId": "c1",
        "arguments": { "query": "test" }
      },
      "metadata": {},
      "timestamp": "2026-02-08T10:00:00.000Z"
    }
  ]
}

Field	Type	Required	Description
events	array	✅	Array of 1–1000 events
events[].sessionId	string	✅	Session identifier
events[].agentId	string	✅	Agent identifier
events[].eventType	string	✅	One of the 18 event types (see below)
events[].severity	string	—	debug / info / warn / error / critical (default: info)
events[].payload	object	✅	Event-type-specific payload
events[].metadata	object	—	Additional metadata (default: {})
events[].timestamp	string	—	ISO 8601 timestamp (default: server time)

Event Types

Type	Payload Fields
session_started	agentName?, agentVersion?, mcpClientInfo?, tags?
session_ended	reason (completed/error/timeout/manual), summary?, totalToolCalls?, totalDurationMs?
tool_call	toolName, callId, arguments, serverName?
tool_response	callId, toolName, result, durationMs
tool_error	callId, toolName, error, errorCode?, durationMs
approval_requested	requestId, action, params, urgency
approval_granted	requestId, action, decidedBy, reason?
approval_denied	requestId, action, decidedBy, reason?
approval_expired	requestId, action, decidedBy, reason?
form_submitted	submissionId, formId, formName?, fieldCount
form_completed	submissionId, formId, completedBy, durationMs
form_expired	submissionId, formId, expiredAfterMs
llm_call	callId, provider, model, messages, systemPrompt?, parameters?, tools?, redacted?
llm_response	callId, provider, model, completion, toolCalls?, finishReason, usage, costUsd, latencyMs, redacted?
cost_tracked	provider, model, inputTokens, outputTokens, totalTokens, costUsd, trigger?
alert_triggered	alertRuleId, alertName, condition, currentValue, threshold, message
alert_resolved	alertRuleId, alertName, resolvedBy?
custom	type, data

Response (201)

{
  "ingested": 1,
  "events": [
    { "id": "01HXYZ...", "hash": "a1b2c3..." }
  ]
}

Errors

Status	Cause
400	Invalid JSON, validation error, or empty events array
500	Storage error

curl Example

curl -X POST http://localhost:3400/api/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer als_your_key" \
  -d '{
    "events": [{
      "sessionId": "sess_01",
      "agentId": "my-agent",
      "eventType": "tool_call",
      "payload": {
        "toolName": "search_database",
        "callId": "call_01",
        "arguments": { "query": "user records" }
      }
    }]
  }'

SDK Example

import { AgentLensClient } from '@agentlensai/sdk';

const client = new AgentLensClient({
  apiUrl: 'http://localhost:3400',
  apiKey: 'als_your_key',
});

await client.ingestEvents([{
  sessionId: 'sess_01',
  agentId: 'my-agent',
  eventType: 'tool_call',
  payload: {
    toolName: 'search_database',
    callId: 'call_01',
    arguments: { query: 'user records' },
  },
}]);

---

GET /api/events

Query events with flexible filters and pagination.

Query Parameters

Parameter	Type	Description
sessionId	string	Filter by session ID
agentId	string	Filter by agent ID
eventType	string	Filter by event type (comma-separated for multiple)
severity	string	Filter by severity (comma-separated)
from	string	Start of time range (ISO 8601)
to	string	End of time range (ISO 8601)
search	string	Full-text search in payloads
order	string	Sort order: asc or desc (default: desc)
limit	number	Results per page (default: 50, max: 500)
offset	number	Pagination offset (default: 0)

Response (200)

{
  "events": [
    {
      "id": "01HXYZ...",
      "timestamp": "2026-02-08T10:00:00.000Z",
      "sessionId": "sess_01",
      "agentId": "my-agent",
      "eventType": "tool_call",
      "severity": "info",
      "payload": { "toolName": "search", "callId": "c1", "arguments": {} },
      "metadata": {},
      "prevHash": null,
      "hash": "a1b2c3..."
    }
  ],
  "total": 1234,
  "hasMore": true
}

curl Example

# Get tool errors in the last 24 hours
curl "http://localhost:3400/api/events?eventType=tool_error&severity=error&from=2026-02-07T00:00:00Z" \
  -H "Authorization: Bearer als_your_key"

---

GET /api/events/:id

Get a single event by ID.

Response (200)

{
  "id": "01HXYZ...",
  "timestamp": "2026-02-08T10:00:00.000Z",
  "sessionId": "sess_01",
  "agentId": "my-agent",
  "eventType": "tool_call",
  "severity": "info",
  "payload": { "toolName": "search", "callId": "c1", "arguments": {} },
  "metadata": {},
  "prevHash": null,
  "hash": "a1b2c3..."
}

Errors

Status	Cause
404	Event not found