Lite Batch

Lite Batch applies the Lite scoring workflow to schedules of up to 100,000 locations. Jobs run asynchronously: upload a CSV, submit it, then poll for the result CSV, interactive HTML report and, when enabled, branded XLSX workbook.

Step 1: Upload the schedule

POST /v1/lite/batch/upload

Send a UTF-8 CSV as a multipart file. Each row must contain either location or both latitude and longitude.

Supported columns are index, location, latitude, longitude, tag, start_date, end_date, start_hour, and end_hour. Date and hour columns are preserved in the result as schedule context but do not affect Lite scores.

index,location,tag
0,London,Property A
1,Manchester,Property B

The response contains a reusable, owner-scoped file ID:

{
  "file_id": "batch-uploads/8df3b640.csv"
}

Lite and In-Depth batch uploads share validation and storage, so an owned file ID returned by either upload route can be submitted to either mode.

Step 2 - Submit job

POST /v1/lite/batch

{
  "file_id": "batch-uploads/8df3b640.csv",
  "calculation_method": "return_period",
  "flood_plus": false
}

An optional Idempotency-Key header makes retries safe. Reusing the key with the same submission returns the original job; changing any option returns HTTP 409.

{
  "job_id": "951b1f60-1f78-45db-969f-1a1d46b379cc",
  "status": "pending",
  "idempotency_key": "portfolio-2026-08-15"
}

Step 3 - Poll job status

GET /v1/lite/batch/{job_id}

Pending and running jobs return their current status and progress:

{
  "job_id": "951b1f60-1f78-45db-969f-1a1d46b379cc",
  "status": "running",
  "attempt": 1,
  "processed_rows": 43720,
  "total_rows": 100000,
  "progress_percentage": 43,
  "error": null
}

Progress counts input rows, including rows that produce failure output. It is capped at 99 while result artefacts are finalised and reaches 100 only after the job completes. A worker restart increments attempt and resets progress for that attempt. Complete jobs return pre-signed links to the available artefacts:

{
  "job_id": "951b1f60-1f78-45db-969f-1a1d46b379cc",
  "status": "complete",
  "attempt": 1,
  "processed_rows": 100000,
  "total_rows": 100000,
  "progress_percentage": 100,
  "result_url": "https://s3.amazonaws.com/...",
  "report_url": "https://s3.amazonaws.com/...",
  "workbook_url": "https://s3.amazonaws.com/..."
}

workbook_url is null when branded workbook generation is disabled, exceeds the deployment's workbook safety limits, or could not be generated. The result CSV remains the authoritative output in every case. The workbook presents one row per location, with score and returned band columns grouped by peril.

The result contains one row per location and returned peril:

index,location,latitude,longitude,tag,start_date,end_date,start_hour,end_hour,peril,score,band,score_colour,status
0,London,51.5074,-0.1278,Property A,2026-08-15,2027-08-14,0,23,Flood,72,Low,#FEDC8E,success

For return-period jobs, the HTML report assigns each location to its riskiest successful band across all returned perils. Its interactive location distribution chart shows the count and percentage in each band and the total schedule size. A separate No Result count identifies locations without a usable successful band. The report also maps successful locations, shows score and band values by peril, identifies failed locations, and records the calculation method and Flood Plus selection. Its hazard triage table initially ranks location-peril results across every returned peril, with an optional peril filter for narrower review. Download actions in the report header link to the result CSV and, when generated, the branded workbook. These embedded pre-signed links expire after seven days.

Individual geocoding or Lite Score Manager failures are written as failed rows while the remaining schedule continues. Failures in job infrastructure, CSV, HTML generation, or storage set the complete job to failed. Branded workbook generation is supplementary and does not prevent CSV and HTML completion.

Cancel

DELETE /v1/lite/batch/{job_id}

Cancellation is cooperative. A request already in progress may finish before the worker observes the cancellation.