Run Results & Integrity

Read a finished run with one verified record per chart: values, chart contract, coverage, integrity seal status, withheld reasons, and stale detection.

GET /v1/chart-to-data/runs/{id} returns one run with its results. A run that is not done has results: null. A finished run has one record per requested chart: chart_id, chart_key, the engine's status and message for the chart, and the result documents values (the customer-facing table of values), chart (the chart contract) and coverage (the coverage report). A bar or category marker-line chart has no values or chart document and returns plain instead, the rows of the category-axis reading. A chart the engine could not read comes back with a status such as EXECUTION_FAILURE; it does not fail the run.

Each record is verified on read against its seal, the run row and the bound inputs. integrity is VERIFIED, FAILED or UNSEALED (records stored before sealing), and integrity_reasons lists why a record failed: SEAL_MALFORMED, CONTENT_MISMATCH, ENGINE_MISMATCH, INPUT_MISMATCH, DOCUMENT_MISMATCH, RUN_MISMATCH, IDENTITY_MISMATCH, MEMBERSHIP_MISMATCH or INPUT_MISSING. The run itself has an integrity, VERIFIED only when its records are exactly the bound request's charts, none empty, duplicated or added, and each is intact. output_valid reports whether the output satisfies the output contract, and is null for a record without output.

A record that is not VERIFIED, whose output does not satisfy the contract, or that sits in a run that is not VERIFIED is returned without values, chart and coverage and with a withheld_reason of INTEGRITY_FAILED, UNSEALED or OUTPUT_INVALID. Its status, message and printed_tick_validation stay, so the reason a chart yielded nothing is still readable. An unsealed record is never reported as verified; a rerun replaces it with a sealed one.

printed_tick_validation reports whether the axes were checked against the tick labels printed on the page. On a record it has status (PASS or NOT_VERIFIED), the number of axes and the number of printed_glyphs; on the run it is PASS only if every chart with values is PASS and nothing is withheld. stale is a separate signal: it is true, with stale_reason INPUTS_NEWER or ENGINE_CHANGED, when the inputs have a newer version or the engine changed since the run. A stale run keeps its integrity and needs another run to reflect the change.

{
  "id": "4c9e1b75-a2d8-4f60-8e13-b7d0a5c42f98",
  "document_id": "d0e4b7a2-3f19-4c68-9a05-b1c7e8f26d34",
  "page_number": 4,
  "input_id": "2f7c9a41-8b06-4d3e-a915-60c8e1d4b7a3",
  "engine_version": "v24-ts-pdfjs-1",
  "status": "done",
  "attempts": 1,
  "error_code": null,
  "error_message": null,
  "results": [
    {
      "chart_id": "p4-c1",
      "chart_key": "p4-c1",
      "status": "COMPLETE",
      "message": "",
      "values": { "...": "customer-facing table of values" },
      "chart": { "...": "chart contract" },
      "coverage": { "...": "coverage report" },
      "printed_tick_validation": { "status": "PASS", "axes": 2, "printed_glyphs": 14 },
      "integrity": "VERIFIED",
      "integrity_reasons": [],
      "output_valid": true
    }
  ],
  "integrity": "VERIFIED",
  "integrity_reasons": [],
  "printed_tick_validation": "PASS",
  "stale": false,
  "stale_reason": null,
  "inputs_version": 3,
  "inputs_digest": "b1c7e8f2..."
}

{
  "chart_id": "p4-c2",
  "chart_key": "p4-c2",
  "status": "COMPLETE",
  "message": "",
  "printed_tick_validation": { "status": "NOT_VERIFIED", "axes": 0, "printed_glyphs": 0 },
  "integrity": "UNSEALED",
  "integrity_reasons": [],
  "output_valid": null,
  "withheld_reason": "UNSEALED"
}