In-Depth Batch

This is our asynchronous endpoint used to process large schedules of risks. The batch workflow has three steps: upload a CSV file, submit a job, then poll for results.

1 - Upload CSV

Upload a schedule of risks as a CSV file.

Request

POST /v1/in-depth/batch/upload

Headers

Header	Required	Description
`X-API-Key`	Yes	Your API key
`Content-Type`	Yes	`multipart/form-data`

Body

Field	Type	Required	Description
`file`	`file`	Yes	CSV file containing the schedule of risks.

The CSV should contain columns matching the fields of an Event object (e.g. location, latitude, longitude, start_date, end_date, start_hour, end_hour, tag).

Example request

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

Note

Replace api.example.com with the actual base URL provided to you.

Success (200)

Field	Type	Description
`file_id`	`string`	Unique identifier for the uploaded file. Use this when submitting a job.

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

2 - Submit job

Submit a batch processing job for a previously uploaded CSV.

Request

POST /v1/in-depth/batch

Headers

Header	Required	Description
`X-API-Key`	Yes	Your API key
`Content-Type`	Yes	`application/json`

Body

Field	Type	Required	Description
`file_id`	`string`	Yes	The `file_id` returned by the upload step.
`perils`	`list[string]`	Yes	Perils to evaluate. See Perils Reference.

Example request

{
  "file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "perils": ["Rain", "MaxWindGust"]
}

Success (200)

Field	Type	Description
`job_id`	`string`	Unique identifier for the batch job.
`status`	`string`	Initial status, always `"pending"`.

{
  "job_id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
  "status": "pending"
}

3 - Poll job status

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

Request

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

Headers

Header	Required	Description
`X-API-Key`	Yes	Your API key

Path parameters

Parameter	Type	Description
`job_id`	`string`	The `job_id` returned by the submit step.

Response - in progress

Returned while the job is still processing or has failed.

Field	Type	Description
`job_id`	`string`	Job identifier.
`status`	`string`	One of `"pending"`, `"running"`, `"failed"`.
`error`	`string\|null`	Error message if the job failed, otherwise `null`.

{
  "job_id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
  "status": "running",
  "error": null
}

Response - complete

Returned once the job has finished successfully.

Field	Type	Description
`job_id`	`string`	Job identifier.
`status`	`string`	`"complete"`.
`result_url`	`string`	Pre-signed URL to download the results CSV.
`report_url`	`string\\|null`	Pre-signed URL to download the HTML report, if available.

{
  "job_id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
  "status": "complete",
  "result_url": "https://s3.amazonaws.com/...",
  "report_url": "https://s3.amazonaws.com/..."
}

Pre-signed URL to an HTML report visualising the results of the uploaded schedule. Returns null if the report is not available for the submitted job.

The result_url will allow you to download a csv. The columns returned will have all those uploaded, i.e. matching the fields of an Event object, plus information about the perils requested.

Field	Type	Description
`peril`	`string`	Description of the peril. String value given by the API Name
`unit`	`string`	Units for the peril given
`threshold`	`string`	Location name, e.g. `"Los Angeles USA"`. Required if `latitude`/`longitude` not provided.
`probability`	`float`	For the threshold given in that row the probability of that threshold occuring for the lat, lon and dates given.
`return_period`	`integer`	The corresponding probabiliy as a return period.
`status`	`string`	Status of the request either 'success' or 'failed'

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.

Errors

Status	Description
401	Missing or invalid API key.
422	Validation error (invalid `file_id`, unrecognised perils, or missing fields), or `job_id` not found.