Skip to main content

List Review Items

List review queue items with GET /v1/review: filter by status, paginate with cursors, and see which extracted records await human approval before export.

The /v1/review queue is Record Review: record-level human decisions on extracted records, before delivery — not ground-truth benchmark results, and distinct from Field Review (/v1/field-reviews), which handles field-level decisions. GET /v1/review lists these items with status filtering and cursor pagination. One review record exists per document × schema × run combination, so re-listing after a re-run never shows duplicate rows for the same result.

Records enter the queue when a structuring run completes, governed by the schema's validation mode. In full mode every completed record is queued as pending; in sample mode a configurable percentage (default 10%) is queued and the rest are marked auto_approved; with validation off, records are created directly as auto_approved. The queue is therefore a policy decision on the schema, not a side effect of confidence scores — low confidence determines which *fields* are flagged on an item, not whether the item exists.

The status vocabulary has five values. pending items await a decision; approved and rejected are the two outcomes this API's action endpoints produce; auto_approved marks records the sampling policy skipped past human review; partial marks records that received per-field decisions through the platform's partial-approval flow. All five appear in list responses and in GET /v1/review/stats, so treat status as an open set when parsing.

Each review item points back to its context: run_id identifies the run that produced the record (a Job or a Pipeline run), document_id the source document, and schema_id the schema the record was extracted against. The overall_confidence score shows how certain the extraction was, which is what most reviewers sort or triage by. Fields that scored below 0.85 during extraction are collected on the record and returned in full by [GET /v1/review/:id](get-review-item).

Pagination is cursor-based over the (created_at, id) tuple: pass limit (1–100, default 20) and follow pagination.next_cursor until has_more is false. pagination.total is the count of records matching your filter, computed with the same predicate as the page itself. The status filter matches a single exact value; an unrecognized value returns an empty page rather than an error, so a typo in status looks like an empty queue.

Visibility follows your source-access rules: records whose source document is hidden from the API key's minting user are dropped from the list, and pagination.total reflects the filtered set so page boundaries stay consistent. The same rule applies to every single-record read and write in this group — a hidden record 404s identically to a missing one, so a key with restricted document visibility can never enumerate or act on records it cannot see.

Filter with status=pending for the active backlog. Approved and rejected records stay queryable through the same endpoint, so you can also use it for audit trails of past decisions.
GET/v1/review

Query parameters

limitintegerMaximum number of results to return (1–100). Default: 20
cursorstringPagination cursor from a previous response.
orderstringSort direction by created_at: asc or desc. Default: desc
statusstringExact-match filter by record status: pending, approved, rejected, auto_approved, or partial.

curl

curl -s "https://api.talonic.com/v1/review?status=pending&limit=20" \
  -H "Authorization: Bearer tlnc_your_api_key"

Response

Response fields

dataarrayArray of review record objects.
data[].idstringReview record UUID.
data[].run_idstringUUID of the run (Job or Pipeline run) this record belongs to.
data[].document_idstringUUID of the associated document.
data[].schema_idstring | nullUUID of the schema used for this record.
data[].statusstringRecord status: pending, approved, rejected, auto_approved, or partial.
data[].overall_confidencenumber | nullAggregate confidence score (0–1).
data[].assigned_tostring | nullUUID of the team member assigned to review this record.
data[].reviewed_bystring | nullUUID of the team member who last reviewed. Stays null for decisions made through the API, which carries no user identity.
data[].reviewed_atstring | nullISO 8601 timestamp of the last review action.
data[].created_atstringISO 8601 creation timestamp.
data[].linksobjectRelated resource URLs (self, action).
pagination.totalintegerTotal number of records 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": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "run_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "document_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "schema_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "status": "pending",
      "overall_confidence": 0.72,
      "assigned_to": null,
      "reviewed_by": null,
      "reviewed_at": null,
      "created_at": "2026-08-12T09:00:00.000Z",
      "links": {
        "self": "/v1/review/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "action": "/v1/review/a1b2c3d4-e5f6-7890-abcd-ef1234567890/action"
      }
    }
  ],
  "pagination": {
    "total": 15,
    "limit": 20,
    "has_more": false,
    "next_cursor": null
  }
}

Errors

Error responses

401unauthorizedMissing or invalid API key.
403insufficient_scopeThe key lacks the read scope. The response names the required and held scopes.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Most integrations poll this endpoint on a schedule to detect new items, then call GET /v1/review/:id to fetch full detail before rendering a review UI. Pair with GET /v1/review/stats to monitor queue depth and set alerting thresholds on the pending count, and with [POST /v1/review/batch](review-batch) to clear high-confidence backlogs in one call.

Frequently asked questions

When do items appear in the review queue?+
A review record is created for each document × schema result when its structuring run completes, according to the schema's validation mode: full mode queues every record as pending, sample mode queues a configurable percentage (default 10%) and auto-approves the rest, and with validation off records are created as auto_approved. Confidence scores decide which fields are flagged on an item, not whether the item exists.
How do I paginate through all review items?+
Pass the `next_cursor` value from the response as the `cursor` query parameter in your next request. Continue until `has_more` is false. The cursor encodes the last row's (created_at, id) position, so new records arriving mid-iteration never cause skipped or duplicated rows.
Can I filter review items by document or schema?+
The list endpoint supports filtering by `status` only. To find review items for a specific document or schema, page through the relevant status and filter client-side on `document_id` or `schema_id` — both appear on every list row.
Do I need to act on auto_approved records?+
No. auto_approved means the schema's sampling policy passed the record without human review; it is already on the approved path. They remain listable for audit, so exclude them client-side (or filter status=pending) when building a work queue.
Why does an item another teammate sees not appear for my key?+
Records are filtered by source-document visibility: if the document behind a record is hidden from the user who minted your API key, the record is dropped from lists and 404s on direct reads. pagination.total reflects the filtered set, so counts differ between keys with different visibility.

Related

Review Queue Statistics
Get Review Item Detail
Approve or Reject an Item
Batch Review Actions
Assign a Reviewer