Endpoints
| Method | Path | Purpose |
|---|---|---|
GET | /traces | List traces |
GET | /traces/stats | Get trace statistics |
GET | /traces/:traceId | Get trace events by trace ID |
GET | /mcp-events | List recent MCP events for current user |
List traces
Query parameters
| Parameter | Type | Description |
|---|---|---|
limit | integer | Items per page (1—200, default 50) |
offset | integer | Number of items to skip |
userId | string | Filter by user ID |
sessionId | string | Filter by session ID |
agentId | string | Filter by application ID |
Trace object
| Field | Type | Description |
|---|---|---|
traceId | string | Unique trace identifier |
sessionId | string | Session that produced this trace |
startedAt | string | ISO 8601 timestamp |
endedAt | string | null | ISO 8601 timestamp (null if in progress) |
eventCount | number | Total events in this trace |
okCount | number | Events with "ok" status |
warnCount | number | Events with "warn" status |
errorCount | number | Events with any error status |
agentId | string | Application ID |
agentName | string | Application name |
ownerUserId | string | User who initiated the trace |
ownerEmail | string | Email of the user |
agentSessionId | string? | Session ID associated with the trace |
agentSessionName | string? | Session name |
Get trace statistics
Query parameters
| Parameter | Type | Description |
|---|---|---|
period | string | Time window: "1d", "7d", or "30d" |
Stats response
REST response is the stats object directly. SDK response shape is{ stats: <stats object> }.
| Field | Type | Description |
|---|---|---|
totalTraces | number | Total traces in the period |
totalEvents | number | Total events across all traces |
eventCounts | object | Breakdown of events by status |
errorRate | number | Percentage of events with error status |
latency | object | Latency percentiles (see below) |
bytesTransferred | object | { in: number, out: number } — bytes received and sent |
errorsByType | object[] | Error counts grouped by type |
topTools | object[] | Most-called tools with call counts |
timeline | object[] | Time-bucketed event counts for charting |
Latency object
| Field | Type | Description |
|---|---|---|
avg | number | Average latency in milliseconds |
p50 | number | Median latency |
p95 | number | 95th percentile latency |
p99 | number | 99th percentile latency |
Get trace events
{ "events": [...] }.
SDK response shape: { "trace": { ... }, "events": [...] } (the SDK synthesizes trace if the API returns only events).
Event object
| Field | Type | Description |
|---|---|---|
id | string | Event ID |
createdAt | string | ISO 8601 timestamp |
sessionId | string | Session identifier from event ingestion |
agentId | string | Application UUID |
traceId | string | null | Trace ID (when present) |
apiKeyId | string | null | API key identifier (if applicable) |
eventType | string | Type of event |
status | string | "ok", "warn", "error_remote", "error_proxy", or "error_auth" |
durationMs | number | null | Time taken in milliseconds |
integrationId | string | null | Integration that handled the call |
toolName | string | null | Name of the tool called |
errorMessage | string | null | Error details (when status is not "ok") |
bytesIn | number | null | Request payload size in bytes |
bytesOut | number | null | Response payload size in bytes |
requestJson | object | null | Request payload (when available) |
responseJson | object | null | Response payload (when available) |
parentEventId | string | null | Parent event ID for nested operations |
agentSessionId | string | null | Agent session UUID |
Event status values
| Status | Meaning |
|---|---|
ok | Tool call completed successfully |
warn | Completed with warnings (e.g., partial results) |
error_remote | The upstream integration returned an error |
error_proxy | Kontext failed to proxy the request |
error_auth | Authentication or authorization failure |
List MCP events
{ "items": [...] }
/mcp-events returns lightweight event records:
| Field | Type | Description |
|---|---|---|
id | string | Event ID |
createdAt | string | ISO 8601 timestamp |
agentId | string | Application UUID |
integrationId | string | null | Integration UUID |
toolName | string | null | Tool name |
eventType | string | Event type |
status | string | Event status |