Batch (asynchronous)

The asynchronous tasks endpoints allow for processing large hazard model requests that may take a significant amount of time to complete. Instead of a single, long-running synchronous request, this endpoint provides a mechanism to initiate a task, monitor its progress, and download the results once ready.

Basic Usage Flow

The general flow for using the asynchronous tasks endpoint involves three main steps:

1. Upload the schedule: You begin by submitting a csv file, specifying the locations (and optionally time period). The API will respond with a unique file_id for your request. This is a quick, synchronous call that simply uploads your batch.

2. Submit job: Once a file is uploaded, you can submit it for a job. In the job you can specify what perils you would like to run from the availble perils

3. Poll job status: You can poll for the job status. This can either return: "pending", "running", "complete", "failed", or "cancelled". After the task has successfully completed, the API provides result_url, report_url and, when enabled, workbook_url. Poll job

Up to 100,000 rows per upload; larger files are split internally.

CSV File structure

The uploaded CSV file must contain a header row and at least 1 data row (minimum schedule size). A single upload may contain at most 100,000 rows. Processing occurs in chunks of up to 10,000 rows internally; larger files are split during execution and returned as a single combined results file.

CSV column headers must be lowercase. The supported columns are:

Each CSV row requires either a non-empty location or both latitude and longitude; coordinate values of 0 are valid. A location with an incomplete coordinate pair is accepted, and both coordinates are geocoded from the location. Missing both options, or providing only one coordinate without a location, is rejected with HTTP 400 and row-level details.

Both date columns may be omitted. For example, this schedule is valid:

location
London
Manchester

If this job is submitted on 2026-08-10, each row defaults to a start_date of 2026-08-10 and an end_date of 2027-08-09. When a row supplies only start_date, its default end_date is calculated from that value. Explicit dates are preserved.

Example

Step 1: Upload the schedule

POST /v1/in-depth/batch/upload

Upload a CSV for batch processing.

Body

By default the CERA draft integration is enabled for the deployment, so a successful weather batch upload also attempts to create a multi entry draft schedule. This allows the results to be visible in the UI with the login details associated with your API key. The draft uses the original filename as its schedule name, PROPERTY as its line of business, and the tenant and organisation metadata associated with the API key. The file is registered without data cleaning.

Multi entry integration does not change this endpoint's response and does not prevent the uploaded file from being submitted as a weather batch job.

Example request

curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@schedule.csv" \
  "https://prod-external-weather-api.birdseyeviewtechnologies.com/v1/in-depth/batch/upload"

Success (200)

{
  "file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Step 2 - Submit job

POST /v1/in-depth/batch

Submit a batch processing job for a previously uploaded CSV.

Headers

Body

Example request

    curl -X POST https://prod-external-weather-api.birdseyeviewtechnologies.com/v1/in-depth/batch \
      -H "Content-Type: application/json" \
      -H "X-API-Key: YOUR_API_KEY" \
      -d '{
        "file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "perils": ["Rain", "MaxWindGust"]
      }'

    import requests

    url = "https://prod-external-weather-api.birdseyeviewtechnologies.com/v1/in-depth/batch"
    headers = {
        "Content-Type": "application/json",
        "X-API-Key": "YOUR_API_KEY"
    }
    payload = {
        "file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "perils": ["Rain", "MaxWindGust"]
    }

    response = requests.post(url, json=payload, headers=headers)
    print(response.json())

Success (200)

{
  "job_id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
  "status": "pending",
  "idempotency_key": "90f141de-a4c9-4d07-9bb2-1dc494dc34ab"
}

Equivalent submissions using the same API key and Idempotency-Key return the original job_id. Reusing a key with a different file_id or peril list returns HTTP 409.

Step 3 - Poll job status

GET /v1/in-depth/batch/{job_id}

Check the status of a submitted batch job. When the job is complete the response includes pre-signed download URLs.

Headers

Path parameters

Example request

    curl -X GET https://prod-external-weather-api.birdseyeviewtechnologies.com/v1/in-depth/batch/f9e8d7c6-b5a4-3210-fedc-ba0987654321 \
      -H "Content-Type: application/json" \
      -H "X-API-Key: YOUR_API_KEY"

    import requests

    url = "https://prod-external-weather-api.birdseyeviewtechnologies.com/v1/in-depth/batch/f9e8d7c6-b5a4-3210-fedc-ba0987654321"
    headers = {
        "Content-Type": "application/json",
        "X-API-Key": "YOUR_API_KEY"
    }

    response = requests.get(url, headers=headers)
    print(response.json())

Response - in progress

Returned while the job is still processing or has failed.

{
  "job_id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
  "status": "running",
  "attempt": 1,
  "processed_rows": 43720,
  "total_rows": 100000,
  "progress_percentage": 43,
  "error": null
}

Progress counts uploaded input rows rather than generated result rows. Rows that produce geocoding or calculation failures still count as processed. A running job stays at 99% while its report and downloadable artefacts are being created. If processing restarts after a worker lease expires, attempt increments and processed_rows resets for the new attempt.

Response - complete

Returned once the job has finished successfully.

```json
{
  "job_id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
  "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/…"
}
```

The XLSX workbook retains the long-form threshold rows and BEV branding. It does not rescale probability values, cap return periods, or derive Lite risk categories. Large results are split across numbered worksheets at Excel's row limit. workbook_url is null when workbook generation is disabled, exceeds the deployment's workbook safety limits, or fails. The CSV remains authoritative and available.

The results CSV

Your original columns, plus per-peril outputs:

Example:

index,location,latitude,longitude,tag,start_date,end_date,start_hour,end_hour,peril,unit,threshold,probability,return_period,status
0,,52.0,-0.1,London,2025-11-27,2025-11-27,0,23,Rain,mm,0,73.9315,1,success
0,,52.0,-0.1,London,2025-11-27,2025-11-27,0,23,Rain,mm,1,44.0262,2,success

These URLs will expire after 1 week.

Optional - Cancel a job

DELETE /v1/in-depth/batch/{job_id}

Cancel a pending or running batch job. Cancellation is cooperative, so an active model request may finish before the worker observes it.

    curl -X DELETE https://prod-external-weather-api.birdseyeviewtechnologies.com/v1/in-depth/batch/f9e8d7c6-b5a4-3210-fedc-ba0987654321 \
      -H "Content-Type: application/json" \
      -H "X-API-Key: YOUR_API_KEY"

The response uses the normal job status shape and reports "cancelled" once the cancellation is stored.

Errors