{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/latitude-so/main/json-schema/latitude-so-trace-detail-schema.json",
  "title": "TraceDetail",
  "x-generated": "2026-10-18",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/latitude-so-openapi.json#/components/schemas/TraceDetail",
  "type": "object",
  "properties": {
    "organizationId": {
      "type": "string",
      "description": "Organization that owns this trace."
    },
    "projectId": {
      "type": "string",
      "description": "Project this trace belongs to."
    },
    "traceId": {
      "type": "string",
      "description": "32-character trace identifier."
    },
    "spanCount": {
      "type": "integer",
      "minimum": 0,
      "description": "Total number of spans in the trace."
    },
    "errorCount": {
      "type": "integer",
      "minimum": 0,
      "description": "Number of spans flagged with an error status."
    },
    "startTime": {
      "type": "string",
      "description": "ISO-8601 timestamp of the trace's earliest span."
    },
    "endTime": {
      "type": "string",
      "description": "ISO-8601 timestamp of the trace's latest span."
    },
    "durationNs": {
      "type": "number",
      "description": "Wall-clock duration of the trace in nanoseconds."
    },
    "timeToFirstTokenNs": {
      "type": "number",
      "description": "Nanoseconds from the start of the first LLM span to its first emitted token. `0` if not measured."
    },
    "tokensInput": {
      "type": "number",
      "description": "Total input tokens across LLM spans."
    },
    "tokensOutput": {
      "type": "number",
      "description": "Total output tokens across LLM spans."
    },
    "tokensCacheRead": {
      "type": "number",
      "description": "Total tokens served from the provider's prompt cache."
    },
    "tokensCacheCreate": {
      "type": "number",
      "description": "Total tokens written to the provider's prompt cache."
    },
    "tokensReasoning": {
      "type": "number",
      "description": "Total reasoning tokens reported by the model."
    },
    "tokensTotal": {
      "type": "number",
      "description": "Sum of all token counters."
    },
    "costInputMicrocents": {
      "type": "number",
      "description": "Cost of input tokens in microcents (100,000,000 per USD)."
    },
    "costOutputMicrocents": {
      "type": "number",
      "description": "Cost of output tokens in microcents (100,000,000 per USD)."
    },
    "costTotalMicrocents": {
      "type": "number",
      "description": "Total cost in microcents (100,000,000 per USD)."
    },
    "sessionId": {
      "type": [
        "string",
        "null"
      ],
      "description": "Conversation/session identifier set by the SDK. `null` when absent."
    },
    "userId": {
      "type": [
        "string",
        "null"
      ],
      "description": "End-user identifier set by the SDK. `null` when absent."
    },
    "simulationId": {
      "type": [
        "string",
        "null"
      ],
      "description": "CUID of the simulation that produced this trace. `null` when not a simulation."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Free-form tags attached at ingest time."
    },
    "models": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Model identifiers seen across the trace's LLM spans."
    },
    "providers": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "LLM-provider identifiers seen across the trace's spans."
    },
    "serviceNames": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "OpenTelemetry `service.name` values seen in the trace."
    },
    "rootSpanId": {
      "type": [
        "string",
        "null"
      ],
      "description": "Identifier of the trace's root span. `null` when no root span has been ingested."
    },
    "rootSpanName": {
      "type": [
        "string",
        "null"
      ],
      "description": "`name` attribute of the root span. `null` when no root span has been ingested."
    },
    "positiveAnnotationCount": {
      "type": "integer",
      "minimum": 0,
      "description": "Number of `passed = true` annotations attached to this trace."
    },
    "negativeAnnotationCount": {
      "type": "integer",
      "minimum": 0,
      "description": "Number of `passed = false` annotations attached to this trace."
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Free-form metadata attached at ingest time."
    },
    "conversation": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/GenAIMessage"
      },
      "description": "Full conversation for the trace, in OpenTelemetry GenAI format: the system instructions, then the messages sent into the trace's last LLM-completion span (the running history at that point), followed by that span's generated output."
    }
  },
  "required": [
    "organizationId",
    "projectId",
    "traceId",
    "spanCount",
    "errorCount",
    "startTime",
    "endTime",
    "durationNs",
    "timeToFirstTokenNs",
    "tokensInput",
    "tokensOutput",
    "tokensCacheRead",
    "tokensCacheCreate",
    "tokensReasoning",
    "tokensTotal",
    "costInputMicrocents",
    "costOutputMicrocents",
    "costTotalMicrocents",
    "sessionId",
    "userId",
    "simulationId",
    "tags",
    "models",
    "providers",
    "serviceNames",
    "rootSpanId",
    "rootSpanName",
    "positiveAnnotationCount",
    "negativeAnnotationCount",
    "metadata",
    "conversation"
  ],
  "$defs": {
    "GenAIMessage": {
      "type": "object",
      "additionalProperties": {
        "nullable": true
      },
      "description": "Message in OpenTelemetry GenAI format (`role` + content parts + optional tool calls)."
    }
  }
}