Document Counts

Count documents matching filter conditions without fetching result pages: read the total field of POST /v1/documents/filter with limit 1 for cheap facet counts.

To count documents matching filter conditions without transferring full result pages, call POST /v1/documents/filter with your conditions and a minimal limit, then read the total field. total is computed over the complete visible match set before pagination is applied, so a limit: 1 request is a cheap count query regardless of how many documents match.

This pattern powers faceted navigation UIs and dashboard summary widgets: run one count request per facet (for example, one per source_id, or one per status value of a field) and render the totals, fetching full document lists only when the user drills in. Because the same conditions serve both the count and the listing, the number on the facet chip always agrees with the rows behind the click.

Counts respect the same Sources-IAM visibility as the filter itself, evaluated as the API key's minting user — a count is the number of matching documents *this key can see*, which is exactly what a UI built on the same key will list. For per-value distributions of a single field, GET /v1/search/field-values is the cheaper primitive: it returns every distinct value with its count in one call instead of one filter call per value.

Counts are live reads of the materialized value store, so they move as documents complete extraction and as materialization catches up. A count that looks low immediately after a bulk ingest usually means the index has not been rebuilt yet — trigger POST /v1/search/materialize once the batch's documents report completed, then re-read. Counts with no field conditions (a bare source_id scope, or none) count documents directly and are not affected by materialization lag.

curl -X POST https://api.talonic.com/v1/documents/filter \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": [
      { "fieldId": "6f1e9a2b-4c3d-4e5f-8a7b-9c0d1e2f3a4b", "operator": "eq", "value": "Acme Corp" }
    ],
    "limit": 1
  }'

{
  "data": [ { "id": "b8b00d51-eecc-49b3-affc-89fee95b9518", "filename": "Invoice-2026-001.pdf" } ],
  "total": 47,
  "links": { "self": "/v1/documents/filter" }
}

for SRC in "a1b2c3d4-e5f6-7890-abcd-ef1234567890" "b2c3d4e5-f6a7-8901-bcde-f12345678901"; do
  TOTAL=$(curl -s -X POST https://api.talonic.com/v1/documents/filter \
    -H "Authorization: Bearer $TALONIC_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"source_id": "'"$SRC"'", "limit": 1}' | jq '.total')
  echo "$SRC: $TOTAL documents"
done