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

# Trace APIs

The Trace APIs enable you to retrieve, filter, analyze, and export execution traces for agent sessions. These APIs help developers inspect runtime behavior, debug workflows, analyze performance, and integrate traces with external observability systems.

## Base URL

`/api/projects/:projectId/sessions`

## Authentication

All APIs require bearer token authentication.

`Authorization: Bearer <TOKEN>`

## Get Session Traces

Retrieve the complete set of traces for a session.

**Endpoint**:`GET /api/projects/:projectId/sessions/:sessionId/traces`

**Example Request**

```bash theme={null}
curl -X GET /api/projects/:projectId/sessions/:sessionId/traces \
  -H "Authorization: Bearer $TOKEN"
```

**Response**

Returns all trace events associated with the specified session.

**Trace Event Types**

The following event types can be retrieved and filtered. Use query parameters to narrow down trace results.

| Event Type       | Description                                                        |
| ---------------- | ------------------------------------------------------------------ |
| `llm_call`       | LLM API call details including model, tokens, latency, and prompts |
| `tool_call`      | Tool invocation with parameters                                    |
| `tool_result`    | Tool execution response                                            |
| `decision`       | Routing or workflow decisions                                      |
| `handoff`        | Transfer between agents                                            |
| `guardrail_eval` | Guardrail evaluation results                                       |
| `state_change`   | Session state or variable updates                                  |
| `error`          | Runtime or execution errors                                        |
| `response`       | Final agent response                                               |

### Filter by Event Type

Retrieve traces for a specific event category.

**Endpoint** : `GET /api/projects/:projectId/sessions/:id/traces?eventType=decision`

**Example**

```bash theme={null}
curl -X GET \
"/api/projects/:projectId/sessions/:id/traces?eventType=decision" \
-H "Authorization: Bearer $TOKEN"
```

### Filter by Decision Kind

Retrieve traces for a specific decision type.

**Endpoint**: `GET /api/projects/:projectId/sessions/:id/traces?decisionKind=handoff`

**Example**

```bash theme={null}
curl -X GET \
"/api/projects/:projectId/sessions/:id/traces?decisionKind=handoff" \
-H "Authorization: Bearer $TOKEN"
```

### Retrieve Child Events for a Span

Get nested events associated with a specific span.

**Endpoint**: `GET /api/projects/:projectId/sessions/:id/traces/:spanId/children`

**Example**

```bash theme={null}
curl -X GET \
/api/projects/:projectId/sessions/:id/traces/:spanId/children \
-H "Authorization: Bearer $TOKEN"
```

### Include Metrics in Trace Response

Include execution metrics along with trace events.

**Endpoint**: `GET /api/projects/:projectId/sessions/:id/traces?include=metrics`

**Example**

```bash theme={null}
curl -X GET \
"/api/projects/:projectId/sessions/:id/traces?include=metrics" \
-H "Authorization: Bearer $TOKEN"
```

## View Aggregated Session Metrics

Retrieve performance metrics aggregated across the session.

**Endpoint**: `GET /api/projects/:projectId/sessions/:id/metrics`

**Example Request**

```bash theme={null}
curl -X GET /api/projects/:projectId/sessions/:id/metrics \
  -H "Authorization: Bearer $TOKEN"
```

Response Includes:

* Total session latency
* Per-turn latency breakdown
* Token usage per LLM call
* Tool call count
* Tool success rate
* Guardrail evaluation count
* Guardrail block rate

## Run Trace Analysis

Run automated diagnostics on session traces.

**Endpoint**: `GET /api/projects/:projectId/sessions/:id/analysis`

**Example Request**

```bash theme={null}
curl -X GET /api/projects/:projectId/sessions/:id/analysis \
  -H "Authorization: Bearer $TOKEN"
```

Response Includes:

* Slow spans
* Error patterns
* Decision anomalies
* Optimization suggestions

## Export Traces

Export traces for offline analysis or integration with observability tools.

### Export Traces as CSV

**Endpoint**: `GET /api/projects/:projectId/sessions/export?format=csv`

**Example Request**

```bash theme={null}
curl -X GET \
"/api/projects/:projectId/sessions/export?format=csv" \
-H "Authorization: Bearer $TOKEN"
```

## Export LLM Generations Across Sessions

Retrieve all LLM call events across sessions.

**Endpoint**: `GET /api/projects/:projectId/sessions/generations`

**Example Request**

```bash theme={null}
curl -X GET /api/projects/:projectId/sessions/generations \
  -H "Authorization: Bearer $TOKEN"
```

**Response**

Returns LLM generation events across sessions, including:

* Model usage
* Token consumption
* Latency
* Prompt metadata