Batch or One Large Document? Designing Reviewable Jobs in Skavio Agent Tools

Choosing between one large processing job and a batch of smaller jobs is a workflow decision, not a file-size contest. Skavio Agent Tools is a company-scoped, authenticated API for asynchronous document, invoice, audio and data processing, with self-service keys and a shared prepaid credit wallet. The useful question is simpler: where does one business record end and the next begin?

Start with the business record, not the upload count

A single PDF can contain several unrelated records, and a single invoice can span several pages. The job boundary should follow the review boundary. If each invoice, order or record needs its own accept-or-reject decision, exception queue, retry path, routing rule or audit trail, separate jobs are usually easier to operate. If all pages share one header, a continued line-item table, appendices or other evidence needed to understand the same transaction, one larger job preserves context. The temptation to merge unrelated records just to reduce job count is usually a mistake. It weakens failure isolation, complicates idempotency and makes it harder to explain which output belongs to which source. Equally, splitting a single logical document at an arbitrary page number can break the evidence chain. Agent Tools output should still pass human review before it reaches accounting or an ERP; the API is not an approval system.

Use batches where failure and review must stay isolated

A batch is an application-layer pattern: one status record per logical document, with its own submission, quote reference, idempotency key, result location and review state. That design lets an operator reject one bad scan without treating every other document in the batch as failed. It also makes retries safer. Use one idempotency key per logical business document, not per upload attempt, so a client or network retry does not accidentally create duplicate work. Skavio's current processing contract states that the submission-time server quote is authoritative, successful jobs settle once and permanent failure releases the credit reservation. That is useful for planning, but it does not remove the need for an internal status model. Do not assume a multi-file submission becomes a set of independently recoverable sub-jobs, or that Agent Tools automatically merges or splits documents. If you need per-record acceptance, retry and audit, build that structure explicitly around separate jobs.

Use one larger job when pages share evidence

Some documents should not be split just because they are long. A multi-page invoice with a single supplier header, continued line items and a closing tax summary is one business record. So is a purchase order whose delivery terms appear on page one and whose quantities continue on later pages. In those cases, the larger job keeps the header, line items and source context together for review. If a source exceeds a documented page or upload constraint, split only where the business record remains understandable. Preserve a manifest that maps each part back to the original document and page range, and plan how a reviewer will see the parts together. Do not rely on automatic merging or an undocumented batch recovery feature. The current Skavio processing contract lists per-upload, queued-job, active-job, page and retention constraints, but verify the live Agent Tools documentation before hard-coding any value into production.

A practical decision rule for operators and developers

The decision rule can be written on one page. First, identify the logical business record. Second, ask whether that record needs its own review decision, retry path, routing destination or audit trail. If yes, submit it as its own job and hold one idempotency key for it. If the pages only make sense together as one transaction, keep them together unless a documented limit forces a split. Then design the surrounding workflow: verify signed completion webhooks before downstream systems trust a completion event, download results through authenticated access, and archive approved outputs in your own system within the documented retention window. Queue depth is not a throughput promise; a documented active-job limit is a planning constraint. The goal is not the smallest number of jobs. It is a processing history that a reviewer can explain, retry and audit.

Explore Skavio Agent Tools →