Skip to main content

List Field Reviews

List the cross-pipeline field-review queue: fields a blocking validation gate or a declarative hold parked for a human decision. Filter by pipeline, trigger, or status.

The field-review queue is the cross-pipeline worklist of fields a blocking validation gate, or a declarative requires_review hold, parked for a human decision before the value becomes canonical. 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

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.

Related

Field Review Summary
Get Field Review
Resolve Field Review