> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kontext.security/llms.txt
> Use this file to discover all available pages before exploring further.

# Traces

> Query trace data and statistics for tool call observability.

Traces capture every tool call flowing through Kontext. Each trace groups the events from a single session interaction, including timing, status, and error details. Use traces to debug failures, monitor error rates, and understand usage patterns.

## 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

<CodeGroup>
  ```bash curl theme={"system"}
  curl "https://api.kontext.security/api/v1/traces?limit=20&agentId=550e8400-e29b-41d4-a716-446655440000" \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```typescript SDK theme={"system"}
  const { items } = await client.traces.list({
    limit: 20,
    agentId: "550e8400-e29b-41d4-a716-446655440000",
  });
  ```
</CodeGroup>

### 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

<CodeGroup>
  ```bash curl theme={"system"}
  curl "https://api.kontext.security/api/v1/traces/stats?period=7d" \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```typescript SDK theme={"system"}
  const { stats } = await client.traces.stats({ period: "7d" });
  ```
</CodeGroup>

### 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

<CodeGroup>
  ```bash curl theme={"system"}
  curl https://api.kontext.security/api/v1/traces/aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```typescript SDK theme={"system"}
  const { trace, events } = await client.traces.get(
    "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
  );
  for (const event of events) {
    console.log(`${event.toolName}: ${event.status} (${event.durationMs}ms)`);
  }
  ```
</CodeGroup>

REST response shape: `{ "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

<CodeGroup>
  ```bash curl theme={"system"}
  curl "https://api.kontext.security/api/v1/mcp-events?limit=100" \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```typescript SDK theme={"system"}
  const { items } = await client.events.list({ limit: 100 });
  ```
</CodeGroup>

Response shape: `{ "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       |