Every converted session is a single JSON file conforming to the minitrace schema (currently minitrace-v0.2.0). This page documents every field, its type, and what it means.

The authoritative Go types live in pkg/minitrace/schema.go. The JSON field names match the struct tags exactly.

Session (top level)

The session is the root object in each .minitrace.json file.

Provenance

Tracks where the session came from so you can trace any converted file back to its original source.

Flags

Data quality signals set during conversion. Most converters set needs_cleaning: true since raw sessions are not curated.

Environment

Captures the model and framework configuration for the session.

Operational Context

Runtime context captured at session start. Availability depends on the source format.

Timing

Temporal information about the session. The privacy_level field controls how much timing detail is exposed.

Turns

The conversation transcript as an ordered array. Each turn is one message from a participant.

Per-turn Usage

Tool Calls

Every tool invocation is recorded with its input, output, and contextual position within the session.

Tool Call Input

A practical querying note: input.file_path is the normalized shared field when the adapter can provide one, while input.arguments preserves the tool-specific raw payload. In SQL, that often means the safest file-oriented pattern is:

COALESCE(tc->'input'->>'file_path', tc->'input'->'arguments'->>'path')

Likewise, shell tools often use:

(tc->'input'->>'command')

and tools such as web search may expose their key values under input.arguments, for example:

(tc->'input'->'arguments'->>'query')

Do not assume every tool uses the same nested keys. When in doubt, inspect a bounded preview of one unnested tool call first.

Tool Call Output

Framework-specific metadata conventions

Minitrace uses a small number of shared first-class fields plus three explicit escape hatches for source-specific detail:

• operational_context.framework_config
• turns[].framework_metadata
• tool_calls[].framework_metadata

Use these when a raw field is analytically useful but not yet stable enough to become shared schema. See go-minitrace help framework-metadata-mappings for the per-adapter mapping tables.

Tool Call Context

Spawned Agent

Present when a tool call delegates to a subagent (e.g., Claude Code's Agent tool).

Metrics

Computed summary statistics. These are calculated during conversion from the turns and tool calls.

Annotations

Optional human or automated labels attached to a session, turn, or tool call.

At the file-format level, annotations live inside the session JSON as the annotations array. In SQL, this appears as the annotations column on sessions_base, and the normal query pattern is:

SELECT ...
FROM sessions_base,
     UNNEST(annotations) AS a(ann)

The annotation object has these fields:

Annotation scope semantics

The scope object is how an annotation is attached to a concrete thing in the transcript.

This distinction matters in analysis because a session-level label answers a different question than a turn-level or tool-call-level label.

Annotation categories

The current built-in categories are:

• observation
• ai-failure
• user-error
• environment-issue
• success
• question
• to-discuss
• to-improve

Taxonomy mappings

taxonomy_mappings is an object containing arrays of codes from three different labeling systems:

Annotation query paths

These are the JSON paths you will most often use in SQL after UNNEST(annotations):

A compact SQL example:

SELECT
  id AS session_id,
  REPLACE(CAST(json_extract(ann, '$.scope.type') AS VARCHAR), '"', '') AS scope_type,
  REPLACE(CAST(json_extract(ann, '$.content.category') AS VARCHAR), '"', '') AS category,
  REPLACE(CAST(json_extract(ann, '$.content.title') AS VARCHAR), '"', '') AS title
FROM sessions_base,
     UNNEST(annotations) AS a(ann);

Coordination

Multi-session coordination metadata.

Quality tiers

Quality is assigned automatically during conversion based on content richness:

• A — Has conversation turns, tool calls with output, more than 10 tool calls, and more than 5 turns
• B — Has conversation turns but does not meet the A threshold
• C — No conversation turns at all

See also

• go-minitrace help what-is-minitrace — conceptual overview
• go-minitrace help writing-duckdb-queries — how to query these fields with SQL
• go-minitrace help adapter-reference — how each source format maps to this schema