Skip to main content

Result Checks

Read validation check outcomes for one structuring result with GET /v1/structuring/results/:id/checks: pass, fail, skip, or error, with message and details.

Check outcomes record how each configured validation check evaluated one structuring result. GET /v1/structuring/results/{id}/checks returns all outcomes for a result in evaluation order, each with a four-way status — pass, fail, skip, or error — plus a human-readable message, the failing field_path, and the expected_value/actual_value pair that makes failures self-explanatory. Use this to understand why a result was flagged, or to build audit trails for data quality.

The id here is a structuring result id (one row of a run), not the run id — you get result ids from Job results (GET /v1/jobs/{id}/results) or from the result_id on pending review items. Outcomes are computed automatically when the result is produced; there is no manual trigger and no re-run. Each outcome also embeds the full check object it was evaluated against, so you can render name, severity, and current config without a second fetch.

skip is a first-class verdict, not a pass: it means the check could not apply — the target field was null, the check type or format was unrecognized, or the evaluator is not implemented (lookup with lookup_source "api", custom_expression). error means the evaluation itself crashed (e.g. an invalid regex) and carries the exception message. Treat both separately from pass/fail in dashboards, or silent misconfiguration will read as 100% passing.
GET/v1/structuring/results/{id}/checks

curl

curl -s https://api.talonic.com/v1/structuring/results/9c2f6a1e-3b7d-4c58-9e21-8f4a5d6b7c80/checks \
  -H "Authorization: Bearer tlnc_your_api_key"

Response

Response fields

dataarrayArray of check outcome objects, ordered by created_at ascending.
data[].idstringCheck outcome UUID.
data[].dataspace_result_idstringUUID of the structuring result this outcome belongs to.
data[].check_idstringUUID of the validation check that was evaluated.
data[].statusstringVerdict: pass, fail, skip, or error.
data[].severitystringThe check's severity at evaluation time, denormalized onto the outcome (warning, error, critical).
data[].messagestring | nullHuman-readable explanation, e.g. "Field \"total_amount\" value 1500000 is out of range [0, 1000000]".
data[].detailsobject | nullStructured extras for some types — field_presence records { present, missing, mode }.
data[].field_pathstring | nullThe field the check targeted, when it targets a single field.
data[].expected_valuestring | nullWhat the check expected — a range, a format name, a regex pattern, or an allowlist preview.
data[].actual_valuestring | nullThe value actually found.
data[].created_atstringISO 8601 evaluation timestamp.
data[].checkobjectThe full validation check object as currently stored (name, type, severity, config, is_active, ...).

Response

{
  "data": [
    {
      "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "dataspace_result_id": "9c2f6a1e-3b7d-4c58-9e21-8f4a5d6b7c80",
      "check_id": "5fee4bba-8380-44b8-9780-5e4548424b3c",
      "status": "fail",
      "severity": "error",
      "message": "Field \"total_amount\" value 1500000 is out of range [0, 1000000]",
      "details": null,
      "field_path": "total_amount",
      "expected_value": "[0, 1000000]",
      "actual_value": "1500000",
      "created_at": "2026-08-29T11:41:12.020Z",
      "check": {
        "id": "5fee4bba-8380-44b8-9780-5e4548424b3c",
        "user_schema_id": "36ef3a00-a4dc-4e49-af6a-66ae20f9b58a",
        "name": "Total amount range",
        "description": "Totals must be plausible",
        "type": "field_range",
        "severity": "error",
        "config": { "field": "total_amount", "min": 0, "max": 1000000 },
        "is_active": true,
        "sort_order": 0
      }
    },
    {
      "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
      "dataspace_result_id": "9c2f6a1e-3b7d-4c58-9e21-8f4a5d6b7c80",
      "check_id": "342e816c-0687-474e-9393-44ed76dca9d8",
      "status": "skip",
      "severity": "warning",
      "message": "Field \"due_date\" is null/missing",
      "details": null,
      "field_path": "due_date",
      "expected_value": null,
      "actual_value": null,
      "created_at": "2026-08-29T11:41:12.020Z",
      "check": {
        "id": "342e816c-0687-474e-9393-44ed76dca9d8",
        "user_schema_id": "36ef3a00-a4dc-4e49-af6a-66ae20f9b58a",
        "name": "Due date is a date",
        "description": null,
        "type": "field_format",
        "severity": "warning",
        "config": { "field": "due_date", "format": "date" },
        "is_active": true,
        "sort_order": 1
      }
    }
  ]
}

Errors

Error responses

400VALIDATION_ERRORThe id path parameter is not a valid UUID.
401unauthorizedMissing or invalid API key.
404RESOURCE_NOT_FOUNDStructuring result not found or does not belong to your organization.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

These outcomes are the raw material for gate decisions: a validation_pass gate rule counts the fail rows (optionally only from critical-severity checks), and the [pending review queue](pending-approvals) is a cross-result feed of exactly the fail and error rows. When triaging a flagged record, this endpoint is the drill-down — the queue tells you *that* a result has issues; this route tells you *which field, expected what, got what*.

One nuance for audit tooling: severity on the outcome row is a snapshot from evaluation time, while the embedded check object reflects the check's current configuration. After you edit a check, old outcomes keep their original verdicts and severity but embed the new config — compare expected_value on the outcome (frozen) rather than check.config (live) when reconstructing why something failed months ago.

Frequently asked questions

Are check outcomes generated automatically?+
Yes. Outcomes are computed when a structuring result is produced: all active checks for the result's schema run in sort_order and each records one row. There is no manual trigger, and editing a check later does not re-evaluate existing results.
What is the difference between fail, skip, and error?+
fail is a real verdict — the data violated the rule. skip means the check could not apply: the target field was null, or the type/format was unrecognized. error means the evaluator itself crashed (for example an invalid regex pattern) and the message carries the exception. Gate validation_pass rules count only fail rows.
Can a result have zero check outcomes?+
Yes. If no active checks are configured for the result's schema, the data array is empty. Such a result faces no check-based obstacles and is governed only by gate rules such as min_confidence.
Where do I get a result id to query?+
From the Jobs API — GET /v1/jobs/{id}/results lists a run's result rows with their ids — or from the result_id field on items in GET /v1/structuring/approvals/pending. The id identifies one structured record, not the run.

Related

List Checks
Update / Delete Check
Pending Review Queue
Approve / Reject a Result
Get Job Results