Reading analysis results

​

The order to read in

​

The extractedData envelope

{
  "extractedData": {
    "company": {
      "legal_name": {
        "value": "ACME TRADING LLC",
        "reasoning": "The legal name on the certificate of good standing matches the account holder on the bank verification letter.",
        "sourceStep": 1
      },
      "state_file_number": {
        "value": null,
        "reasoning": "The state file number was not included in the extraction result.",
        "sourceStep": 1
      }
    },
    "ubo_register": [
      { "name": { "value": "John Carter", "reasoning": "Row 1 of the beneficial ownership certification", "sourceStep": 6 },
        "share_pct": { "value": 60, "reasoning": "Row 1 of the beneficial ownership certification", "sourceStep": 6 } }
    ]
  }
}

• A field that got no value still holds its place, as value: null. The field list in extractedData always matches the output schema.
• When a parent object itself was not produced, the paths beneath it are not created. In that case details[] carries one entry for the parent with reasonCode: "PARENT_MISSING".
• reasoning is stored at the moment the analysis completes. Reading the analysis again never changes it.
• sourceStep is an execution order number, so it can differ from the next analysis onward if you edit the workflow. To point at a step reliably, use agentAuditLog.steps[].work_id.
• 0 and false are valid values. Emptiness means null / "" / [] / {}.

​

When there is no envelope

​

Why a field is empty

{
  "category": "JSON_OUTPUT",
  "type": "OUTPUT_MISSING",
  "target": "company.state_file_number",
  "reasonCode": "NOT_IN_FINAL_OUTPUT",
  "message": "The legal name and the registered agent were confirmed on the certificate, but no state file number entry was found.",
  "stepId": 1
}

• reasonCode is an extensible enum. Handle a value outside the table without erroring. It is a separate axis from type (a fixed set of six, such as OUTPUT_MISSING and OUTPUT_EMPTY).
• reasonCode, message, and stepId appear only on JSON_OUTPUT entries, never on STEP or TOOL entries.
• message is the grounds the responsible step recorded, while the envelope’s reasoning gives the reason at the field level. The two sentences can differ, so read reasoning first for field-level context.
• target is a real instance path. Arrays are expanded by index, one per element (ubo_register[0].name). An empty array, or a missing array key, counts as a single ubo_register entry.
• Omni does not re-examine the original document. It never claims “the value was not in the document”; the strongest statement it makes is “it was not included in the extraction result” (NOT_IN_FINAL_OUTPUT).

​

When no reason can be supplied

​

Do not use extractionStatus

​

Reading the verdict values

​

confidence vs confidenceScore

​

Which playbook produced this verdict

​

Reading the audit log

• Identifying a step: step is the execution order and work_id is the fixed ID of the playbook action. It corresponds to workflowActions[].workId from GET /workflows/:workflowId.
• Step verdicts: status (passed / needs_review / failed) and reasoning are what the Summary tab shows as the reasoning line in the dashboard. rule is the instruction that step carried out.
• External engine calls: judge failure from success and error_code in mcpcalls[]. There is no HTTP status code. fallback_to_rag: true means it fell back to document search after the engine failed.
• To see the same calls organized by action, use rawActionResults.{action}.mcpResults[]. That side uses camelCase (durationMs, errorCode, fallbackToRag).
• A step that never ran does not appear in systemMetadata.workflowHistory[] either. The full step definitions are in workflowActions on the workflow response, and an unexecuted step is recorded in details[] as STEP_NOT_EXECUTED.

​

A pattern for downstream handling

a = get_analysis(analysis_id)
if a["status"] != "completed":
    return retry_later()

fmt = a.get("systemMetadata", {}).get("outputFormatting")
raw_mode = fmt is None and a["outputSchema"] is None or (fmt and fmt["status"] in ("skipped", "fallback_raw"))

if a["verificationStatus"] == "verified" and a["confidence"]["score"] >= 80 and not raw_mode:
    approve(a["extractedData"])
elif a["verificationStatus"] == "rejected":
    reject(reason=[s for s in a["agentAuditLog"]["steps"] if s["status"] == "failed"])
else:
    route_to_reviewer(a, missing=[d for d in a["details"] if d["category"] == "JSON_OUTPUT"])

• Showing a reviewer the target, reasonCode, and message from details[] alongside the envelope’s reasoning makes the cause much faster to find.
• Re-analyzing the same profile after improving the items issues a new analysisId. The earlier result is kept, and you can compare them with the run selector in the dashboard.
• When you need a report a person can read, get the PDF from GET /analyses/:analysisId/report.