Audit Trace API

Endpoints

GET /api/v1/conversation/audit/{conversationId}
GET /api/v1/conversation/audit/{conversationId}/trace

`/audit/{conversationId}/trace` response shape

AuditTraceService derives this from ordered ce_audit rows.

Trace response

JSON

{
  "conversationId": "9bf7540a-b129-4685-a120-730e8a0cb94b",
  "steps": [
    {
      "step": "IntentResolutionStep",
      "stepClass": "com.github.salilvnair.convengine.engine.steps.IntentResolutionStep",
      "sourceFile": "IntentResolutionStep.java",
      "status": "OK",
      "startedAt": "2026-03-13T00:22:01.102Z",
      "endedAt": "2026-03-13T00:22:01.147Z",
      "durationMs": 45,
      "error": null,
      "stages": []
    }
  ],
  "stages": [
    {
      "auditId": 12031,
      "stage": "STEP_ENTER",
      "createdAt": "2026-03-13T00:22:01.102Z",
      "payload": {
        "step": "IntentResolutionStep"
      }
    }
  ]
}

How step status is computed

Trace builder rules

Audit stage	Effect in trace
STEP_ENTER	Opens a step frame with status RUNNING
STEP_EXIT	Closes step frame with status OK
STEP_ERROR	Closes step frame with status ERROR and maps error message

Current important audit stages (active runtime)

High-signal stages

Family	Stages
Pipeline lifecycle	STEP_ENTER, STEP_EXIT, STEP_ERROR, ASSISTANT_OUTPUT, ENGINE_KNOWN_FAILURE, ENGINE_UNKNOWN_FAILURE
Intent + schema	INTENT_RESOLVE_START, INTENT_CLASSIFICATION_MATCHED, INTENT_COLLISION_RESOLVED, SCHEMA_EXTRACTION_START, SCHEMA_STATUS
Rules	RULE_MATCH, RULE_APPLIED, RULE_NO_MATCH
Response	RESOLVE_RESPONSE, RESOLVE_RESPONSE_SELECTED, RESPONSE_EXACT, EXACT_RESPONSE_RENDERING
MCP planner/tool	MCP_PLAN_LLM_INPUT, MCP_PLAN_LLM_OUTPUT, MCP_TOOL_CALL, MCP_TOOL_RESULT, MCP_TOOL_ERROR, MCP_FINAL_ANSWER, MCP_DB_SQL_EXECUTION
Semantic interpret/query	SEMANTIC_INTERPRET_INPUT, SEMANTIC_INTERPRET_LLM_INPUT, SEMANTIC_INTERPRET_LLM_OUTPUT, SEMANTIC_INTERPRET_OUTPUT, SEMANTIC_QUERY_LLM_INPUT, SEMANTIC_QUERY_LLM_OUTPUT, SEMANTIC_QUERY_LLM_RETRY_INPUT, SEMANTIC_QUERY_LLM_RETRY_OUTPUT
Dynamic SQL	DYNAMIC_SQL_EXECUTION, DYNAMIC_SQL_EXECUTION_ERROR

Complete stage enum source

Stage enum lives in ConvEngineAuditStage and includes compatibility/legacy constants in addition to active runtime stages.

Why use both audit endpoints

/audit/{conversationId}: raw forensic payload for root-cause debugging
/audit/{conversationId}/trace: normalized step/stage timeline for UI and runbooks

Endpoints​

/audit/{conversationId}/trace response shape​

How step status is computed​