List Field Reviews

List fields parked for human review in document extraction: every value a validation gate or requires_review hold stopped, filterable by pipeline or trigger.

The field-review queue is Talonic's human-in-the-loop review surface for document extraction: the cross-pipeline worklist of extracted fields that a blocking validation gate, or a declarative requires_review hold, parked for a human decision before the value becomes canonical. Field Review is the cell-level arm of Review: every decision settles one value in one document. Record-level review, where a whole record is approved or rejected, lives at /v1/review. A held field never reaches a delivered data product with its value visible: it surfaces with status only until someone approves the held value or promotes a replacement. This endpoint lists the pending queue, newest-requested first.

Filter the queue with pipeline_id to scope to one run, trigger to separate gate failures from declarative holds, and status to narrow to a particular field state. Each item identifies the held field by its pipeline document id and field key, carries the current value, a confidence score, and a classified reason, plus links to the item's detail and resolve endpoints.

Pagination is cursor-based: pass the next_cursor from the previous response as cursor to page through the queue. The cursor is opaque. Note that the status filter is applied to each page after it is fetched, so a page may return fewer items than the limit when a status filter is active. This endpoint requires an API key with the read scope.

The trigger filter takes gate (a blocking validation gate failed) or declarative (a requires_review field held at the end of the pipeline). Omit it to see both.

GET/v1/field-reviews

Query parameters

pipeline_idstringScope to one pipeline run (UUID).

triggerstringFilter by what parked the field: gate or declarative.

statusstringFilter by field state, e.g. blocked or pending_review.

limitintegerMaximum number of results to return. Default: 20

cursorstringPagination cursor from a previous response.

curl

Response

Response fields

dataarrayArray of queue items.

data[].pipeline_document_idstringPipeline document holding the field.

data[].field_keystringSchema field key under review.

data[].field_display_namestring | nullHuman-readable field name.

data[].statusstringField state: blocked or pending_review.

data[].triggerstring | nullWhat parked the field: gate or declarative.

data[].reasonstringClassified review reason (e.g. missing_value, failed_check, low_confidence).

data[].current_valueanyThe held value as currently stored.

data[].confidencenumber | nullConfidence score of the current value (0-1).

data[].requested_atstring | nullISO 8601 time the field was parked for review.

data[].pipelineobject | nullThe owning run: { id, name }.

data[].documentobject | nullThe source document: { id, name }.

data[].linksobjectItem URLs (self, resolve).

pagination.totalintegerTotal items in the pending queue matching the query.

pagination.limitintegerMaximum results per page.

pagination.has_morebooleanWhether more results exist beyond this page.

pagination.next_cursorstring | nullCursor to fetch the next page. Null if no more results.

Response

{
  "data": [
    {
      "pipeline_document_id": "pd_uuid_1",
      "field_key": "total_amount",
      "field_display_name": "Total Amount",
      "status": "blocked",
      "trigger": "gate",
      "reason": "failed_check",
      "current_value": "12,500.00",
      "confidence": 0.62,
      "requested_at": "2024-09-14T11:02:33.000Z",
      "pipeline": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Lease Agreement — 2024-09-14" },
      "document": { "id": "doc_uuid_1", "name": "lease_oct.pdf" },
      "links": {
        "self": "/v1/field-reviews/pd_uuid_1/total_amount",
        "resolve": "/v1/field-reviews/pd_uuid_1/total_amount/resolve"
      }
    }
  ],
  "pagination": {
    "total": 8,
    "limit": 20,
    "has_more": false,
    "next_cursor": null
  }
}

Errors

Error responses

401unauthorizedMissing or invalid API key.

429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

List Field Reviews

Response

Errors

Related