Asynchronous Tasks

The asynchronous tasks endpoints allow for processing large geospatial data 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.

Asynchronous endpoints have different limits than synchronous endpoints - see Limits for details.

Basic Usage Flow

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

Initiating a Task: You begin by submitting a large polygon request, specifying the polygon geometry and the desired layer IDs. The API will respond with a unique task_id for your request. This is a quick, synchronous call that simply registers your task.
Monitoring Task Status: Once a task is initiated, it enters a processing queue. You can periodically query the API using the task_id to check its current status. The status will indicate whether the task is pending, processing, complete, or has encountered an error. It is crucial to wait until the task status is COMPLETE before attempting to download results. If the task status is ERROR, details about the failure will be provided.
Downloading Results: After the task has successfully completed, the API provides a download_url. This URL can be used to retrieve a zip file containing the processed results.

Zip File Structure

The downloaded zip file contains the following:

TIFF files: For each requested layer that contained data within the specified polygon, a GeoTIFF file is included, named after its layer_id (e.g., your_layer_id.tif). These files contain the geospatial data for the respective layers.
manifest.csv: This CSV file provides a summary of all requested layers and their processing outcomes. It contains two columns:
layer_id: The identifier of the requested layer.
result_code: The status of the processing for that layer. Common values include POLYGON_RESULT_CODE_OK ( indicating data was found and a TIFF file is included) or POLYGON_RESULT_CODE_OUT_OF_BOUNDS (indicating no data was found for that layer within the specified polygon).

Example

If a task was created using the Python SDK with these layer IDs:

layer_ids = [
    "GLOBAL-1ARCSEC-NW_OFFSET-1in103-PLUVIAL-DEFENDED-DEPTH-dT1.10-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in103-PLUVIAL-DEFENDED-DEPTH-dT1.30-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in103-PLUVIAL-DEFENDED-DEPTH-dT1.20-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in103-PLUVIAL-DEFENDED-DEPTH-dT1.00-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in103-PLUVIAL-DEFENDED-DEPTH-dT1.40-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in103-PLUVIAL-DEFENDED-DEPTH-dT1.50-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in50-PLUVIAL-DEFENDED-DEPTH-dT1.20-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in50-PLUVIAL-DEFENDED-DEPTH-dT1.30-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in50-PLUVIAL-DEFENDED-DEPTH-dT1.10-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in50-PLUVIAL-DEFENDED-DEPTH-dT1.40-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in75-PLUVIAL-DEFENDED-DEPTH-dT1.00-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in201-COASTAL-DEFENDED-DEPTH-2049-SSP1_2.6-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in201-COASTAL-DEFENDED-DEPTH-2045-SSP1_2.6-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in201-COASTAL-DEFENDED-DEPTH-2042-SSP1_2.6-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in201-COASTAL-DEFENDED-DEPTH-2052-SSP1_2.6-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in201-COASTAL-DEFENDED-DEPTH-2057-SSP1_2.6-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in150-PLUVIAL-DEFENDED-DEPTH-dT1.30-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in199-PLUVIAL-DEFENDED-DEPTH-dT1.10-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in75-PLUVIAL-DEFENDED-DEPTH-dT1.50-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in150-PLUVIAL-DEFENDED-DEPTH-dT1.10-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in199-PLUVIAL-DEFENDED-DEPTH-dT1.00-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in150-PLUVIAL-DEFENDED-DEPTH-dT1.20-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in150-PLUVIAL-DEFENDED-DEPTH-dT1.40-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in199-PLUVIAL-DEFENDED-DEPTH-dT1.30-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in199-PLUVIAL-DEFENDED-DEPTH-dT1.40-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in175-PLUVIAL-DEFENDED-DEPTH-dT1.00-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in175-PLUVIAL-DEFENDED-DEPTH-dT1.10-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in175-PLUVIAL-DEFENDED-DEPTH-dT1.20-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in175-PLUVIAL-DEFENDED-DEPTH-dT1.30-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in75-PLUVIAL-DEFENDED-DEPTH-dT1.10-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in175-PLUVIAL-DEFENDED-DEPTH-dT1.40-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in299-COASTAL-DEFENDED-DEPTH-2042-SSP1_2.6-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in299-COASTAL-DEFENDED-DEPTH-2045-SSP1_2.6-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in75-PLUVIAL-DEFENDED-DEPTH-dT1.30-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in199-PLUVIAL-DEFENDED-DEPTH-dT1.20-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in299-COASTAL-DEFENDED-DEPTH-2052-SSP1_2.6-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in299-COASTAL-DEFENDED-DEPTH-2057-SSP1_2.6-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in75-PLUVIAL-DEFENDED-DEPTH-dT1.40-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in299-COASTAL-DEFENDED-DEPTH-2049-SSP1_2.6-PERCENTILE50-v3.0",
    "GLOBAL-1ARCSEC-NW_OFFSET-1in175-PLUVIAL-DEFENDED-DEPTH-dT1.50-PERCENTILE50-v3.0",
]

poly = polygon(...)

client = Client(...)
create_resp = client.async_tasks.create_large_polygon_task(poly, layer_ids)
# ...poll for result

After downloading and extracting the zip file, it might look like:

manifest.csv
GLOBAL-1ARCSEC-NW_OFFSET-1in50-PLUVIAL-DEFENDED-DEPTH-dT1.20-PERCENTILE50-v3.0.tif
GLOBAL-1ARCSEC-NW_OFFSET-1in50-PLUVIAL-DEFENDED-DEPTH-dT1.30-PERCENTILE50-v3.0.tif
GLOBAL-1ARCSEC-NW_OFFSET-1in50-PLUVIAL-DEFENDED-DEPTH-dT1.10-PERCENTILE50-v3.0.tif
GLOBAL-1ARCSEC-NW_OFFSET-1in50-PLUVIAL-DEFENDED-DEPTH-dT1.40-PERCENTILE50-v3.0.tif
GLOBAL-1ARCSEC-NW_OFFSET-1in75-PLUVIAL-DEFENDED-DEPTH-dT1.00-PERCENTILE50-v3.0.tif
GLOBAL-1ARCSEC-NW_OFFSET-1in75-PLUVIAL-DEFENDED-DEPTH-dT1.50-PERCENTILE50-v3.0.tif
GLOBAL-1ARCSEC-NW_OFFSET-1in75-PLUVIAL-DEFENDED-DEPTH-dT1.10-PERCENTILE50-v3.0.tif
GLOBAL-1ARCSEC-NW_OFFSET-1in75-PLUVIAL-DEFENDED-DEPTH-dT1.30-PERCENTILE50-v3.0.tif
GLOBAL-1ARCSEC-NW_OFFSET-1in75-PLUVIAL-DEFENDED-DEPTH-dT1.40-PERCENTILE50-v3.0.tif

And the manifest:

layer_id,result_code
GLOBAL-1ARCSEC-NW_OFFSET-1in103-PLUVIAL-DEFENDED-DEPTH-dT1.10-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in103-PLUVIAL-DEFENDED-DEPTH-dT1.30-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in103-PLUVIAL-DEFENDED-DEPTH-dT1.20-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in103-PLUVIAL-DEFENDED-DEPTH-dT1.00-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in103-PLUVIAL-DEFENDED-DEPTH-dT1.40-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in103-PLUVIAL-DEFENDED-DEPTH-dT1.50-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in50-PLUVIAL-DEFENDED-DEPTH-dT1.20-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OK
GLOBAL-1ARCSEC-NW_OFFSET-1in50-PLUVIAL-DEFENDED-DEPTH-dT1.30-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OK
GLOBAL-1ARCSEC-NW_OFFSET-1in50-PLUVIAL-DEFENDED-DEPTH-dT1.10-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OK
GLOBAL-1ARCSEC-NW_OFFSET-1in50-PLUVIAL-DEFENDED-DEPTH-dT1.40-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OK
GLOBAL-1ARCSEC-NW_OFFSET-1in75-PLUVIAL-DEFENDED-DEPTH-dT1.00-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OK
GLOBAL-1ARCSEC-NW_OFFSET-1in201-COASTAL-DEFENDED-DEPTH-2049-SSP1_2.6-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in201-COASTAL-DEFENDED-DEPTH-2045-SSP1_2.6-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in201-COASTAL-DEFENDED-DEPTH-2042-SSP1_2.6-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in201-COASTAL-DEFENDED-DEPTH-2052-SSP1_2.6-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in201-COASTAL-DEFENDED-DEPTH-2057-SSP1_2.6-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in150-PLUVIAL-DEFENDED-DEPTH-dT1.30-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in199-PLUVIAL-DEFENDED-DEPTH-dT1.10-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in75-PLUVIAL-DEFENDED-DEPTH-dT1.50-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OK
GLOBAL-1ARCSEC-NW_OFFSET-1in150-PLUVIAL-DEFENDED-DEPTH-dT1.10-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in199-PLUVIAL-DEFENDED-DEPTH-dT1.00-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in150-PLUVIAL-DEFENDED-DEPTH-dT1.20-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in150-PLUVIAL-DEFENDED-DEPTH-dT1.40-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in199-PLUVIAL-DEFENDED-DEPTH-dT1.30-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in199-PLUVIAL-DEFENDED-DEPTH-dT1.40-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in175-PLUVIAL-DEFENDED-DEPTH-dT1.00-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in175-PLUVIAL-DEFENDED-DEPTH-dT1.10-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in175-PLUVIAL-DEFENDED-DEPTH-dT1.20-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in175-PLUVIAL-DEFENDED-DEPTH-dT1.30-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in75-PLUVIAL-DEFENDED-DEPTH-dT1.10-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OK
GLOBAL-1ARCSEC-NW_OFFSET-1in175-PLUVIAL-DEFENDED-DEPTH-dT1.40-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in299-COASTAL-DEFENDED-DEPTH-2042-SSP1_2.6-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in299-COASTAL-DEFENDED-DEPTH-2045-SSP1_2.6-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in75-PLUVIAL-DEFENDED-DEPTH-dT1.30-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OK
GLOBAL-1ARCSEC-NW_OFFSET-1in199-PLUVIAL-DEFENDED-DEPTH-dT1.20-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in299-COASTAL-DEFENDED-DEPTH-2052-SSP1_2.6-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in299-COASTAL-DEFENDED-DEPTH-2057-SSP1_2.6-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in75-PLUVIAL-DEFENDED-DEPTH-dT1.40-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OK
GLOBAL-1ARCSEC-NW_OFFSET-1in299-COASTAL-DEFENDED-DEPTH-2049-SSP1_2.6-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS
GLOBAL-1ARCSEC-NW_OFFSET-1in175-PLUVIAL-DEFENDED-DEPTH-dT1.50-PERCENTILE50-v3.0,POLYGON_RESULT_CODE_OUT_OF_BOUNDS

Note that the 'out of bounds' results do not have an associated GeoTIFF in the output file.