Batches

Bulk uploads create a batch plus one job per file. Use the batch endpoints to track folder-level progress, inspect all jobs in the batch, and export completed structured results.

Base path: /batches

---

List batches

GET /batches

Returns your bulk-upload batches with pagination and optional filters.

Query parameter	Type	Default	Description
search	string	—	Case-insensitive search over the batch folder name.
status	string	—	Filter by status, for example queued, processing, or completed.
page	integer	1	Page number.
limit	integer	20	Items per page, max 100.

curl "https://netraocr.shivicx.com/api/v1/batches?page=1&limit=20" \
  -u "ak_live_xxxxxxxx:sk_live_xxxxxxxx"

Response 200 OK

{
  "batches": [
    {
      "batch_id": "batch_...",
      "folder_name": "June invoices",
      "status": "processing",
      "total_jobs": 20,
      "completed_jobs": 12,
      "failed_jobs": 0,
      "pending_jobs": 8,
      "progress_percentage": 60,
      "total_pages": 48,
      "coins_consumed": 24,
      "fraud_coins_consumed": 0,
      "template_id": "gl1",
      "enable_fraud_check": false,
      "created_at": "2026-06-16T10:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "total_pages": 1
}

---

Get batch detail

GET /batches/{batch_id}

Returns batch metadata plus a paginated list of jobs in that batch.

Query parameter	Type	Default	Description
jobs_page	integer	1	Job page number.
jobs_limit	integer	50	Jobs per page, max 200.

curl "https://netraocr.shivicx.com/api/v1/batches/batch_...?jobs_page=1&jobs_limit=50" \
  -u "ak_live_xxxxxxxx:sk_live_xxxxxxxx"

Each job item includes job_id, document_id, status, progress, processing time, usage fields, page count, and integrity status.

---

Export batch results

GET /batches/{batch_id}/export

Exports structured OCR results for completed jobs in the batch as a JSON array. Use job_ids to export a subset.

Query parameter	Type	Default	Description
job_ids	string	—	Optional comma-separated job IDs to include.

curl "https://netraocr.shivicx.com/api/v1/batches/batch_.../export" \
  -u "ak_live_xxxxxxxx:sk_live_xxxxxxxx"

Response 200 OK

[
  {
    "job_id": "8f3c...",
    "filename": "invoice.pdf",
    "structured_data": {
      "invoice_number": "INV-1024",
      "total": "1180.00"
    },
    "page_count": 1,
    "pages": []
  }
]

note

Only completed jobs with structured data are included. If the batch has no completed structured results yet, the API returns 404.

See OCR → Bulk processing for the upload flow.