Trace schema

type Trace = {
  trace_id: string;                 // tr_…
  project_id?: string;              // optional in SDK writes
  name: string;
  run_type?: string;
  status: "success" | "error" | "running";
  started_at: string;               // ISO-8601
  ended_at: string | null;
  latency_ms: number | null;
  error_message?: string;
  steps: Step[];
  attachments: Attachment[];
  metadata: Record<string, unknown>;
  token_usage?: { input?: number; output?: number; total?: number };
  cost_usd: number | null;
};

type Step = {
  step_id: string;                  // st_…
  parent_step_id: string | null;
  index?: number;
  name: string;
  type: "llm" | "tool" | "retrieval" | "robotics" | "human" | "annotation" | "custom";
  status: "success" | "error" | "running";
  started_at: string;
  latency_ms: number | null;
  model?: string;
  messages?: Message[];
  tool_calls?: ToolCall[];
  metadata?: Record<string, unknown>;
  token_usage?: { input?: number; output?: number; total?: number };
  attachments: Attachment[];
};

type Message = {
  role: "system" | "user" | "assistant" | "tool";
  content: ContentPart[];
};

type ContentPart =
  | { type: "text"; text: string }
  | { type: "image" | "audio" | "video" | "file" | "sensor"; uri: string; mime?: string; size_bytes?: number };