Event & trace schema

Required fields for trace ingestion (MVP).

Required top-level fields

POST /api/v1/telemetry/traces with JSON body. Minimum viable payload includes trace metadata and at least one span.

{
  "trace": {
    "name": "support_ticket_resolution",
    "metadata": { "environment": "production" }
  },
  "spans": [
    {
      "name": "tool_call",
      "kind": "tool",
      "start_time": "2026-04-12T12:00:00.000Z",
      "end_time": "2026-04-12T12:00:01.200Z",
      "attributes": {
        "tool.name": "search_kb",
        "tool.args_summary": "query=refund policy"
      }
    }
  ]
}

Enums

Span kind accepts llm, tool, chain, retrieval. Use ISO-8601 timestamps for times. A trace carries 1 to 500 spans; optional trace.asset_id, trace.intent (task, allowed_tools, sensitivity) and policy fields are accepted. Authenticate with an org API key as a Bearer token. Send an Idempotency-Key header for safe retries: a new trace returns 201, a replay of the same key returns 200.