Review Stats

Monitor the review backlog with GET /v1/review/stats: per-status record counts for dashboards, alerting on pending queue depth, and review throughput.

GET /v1/review/stats returns a summary of the Record Review queue: the total number of validation records in your workspace and a by_status breakdown. Use it to monitor backlog size, track review throughput, and trigger alerts when pending items exceed a threshold. It is a single aggregate query, so it stays cheap to poll even when the underlying queue holds hundreds of thousands of records.

The by_status object is keyed by whichever statuses actually exist on your records — pending, approved, rejected, auto_approved, and partial are the possible keys. Statuses with zero records are omitted rather than reported as 0, and a workspace with no review records at all returns { "total": 0, "by_status": {} }. Guard your dashboard code with defaults (by_status.pending ?? 0) instead of assuming every key is present.

The counts cover every run and schema in the workspace; there is no per-schema or per-run breakdown on this endpoint. To decompose the backlog, list GET /v1/review?status=pending and group client-side by schema_id — the list rows carry both schema_id and run_id. The auto_approved count is also the fastest way to verify a schema's sampling policy is doing what you expect: it should grow in proportion to (100 − sample rate) percent of completed records.

One scoping difference from the list endpoint matters for restricted keys: stats are computed over all records in the workspace, while GET /v1/review drops records whose source document is hidden from the key's minting user. A key operating under source-visibility rules can therefore see a pending count here that is higher than the number of rows its own list call returns. Alert on stats, but drive work assignment from the list.

Stats also close the loop on review policy tuning. If pending grows faster than your reviewers clear it, lower the schema's sampling rate or move it out of full-validation mode; if rejected stays near zero over a long window, the sample is telling you extraction quality supports a lower rate. Because the endpoint is a point-in-time aggregate, compute rates yourself by differencing successive samples — the API keeps no history of past counts.

curl -s https://api.talonic.com/v1/review/stats \
  -H "Authorization: Bearer tlnc_your_api_key"

Response

{
  "total": 1260,
  "by_status": {
    "pending": 15,
    "approved": 230,
    "rejected": 15,
    "auto_approved": 1000
  }
}

Errors

This endpoint is typically called on a dashboard polling loop to drive queue-depth indicators. A practical alerting pattern: sample by_status.pending every minute, alert when it crosses your SLA threshold, and compute throughput as the delta of approved + rejected between samples. Once the pending count crosses the threshold, fetch the actual items with [GET /v1/review?status=pending](list-review-items) and distribute them via [POST /v1/review/:id/assign](review-assign).