Run RasterFlow Tasks

Every RasterFlow workflow is a task in the Tasks API. You start a task run, poll it until it finishes, then read its output URI from results.

Run a task

Inside a Wherobots notebook or job, the Wherobots Python SDK uses your Wherobots credentials. Anywhere else, set a Wherobots API key in WHEROBOTS_API_KEY. The SDK needs Python 3.11 or later.

# pip install wherobots-python-sdk
import time

import wherobots

wb = wherobots.Wherobots()  # outside Wherobots, reads WHEROBOTS_API_KEY

started = wb.tasks.run("predict_mosaic_geometries_recipe", {
    "aoi": "s3://wherobots-examples/rasterflow/aois/collegepark.parquet",
    "start": "2023-01-01T00:00:00Z",
    "end": "2023-12-31T00:00:00Z",
    "model_recipe": "sam3-text-geometry",
    "text_prompt": ["roofs"],
    "confidence_threshold": 0.3,
}, name="College Park roofs", region="aws-us-west-2")

run = wb.task_runs.get(started.task_run_id)
while run.is_active:
    time.sleep(30)
    run = wb.task_runs.get(run.task_run_id)

print(run.state, run.results, run.error_message)

curl -X POST "https://api.cloud.wherobots.com/tasks/predict_mosaic_geometries_recipe/runs" \
  -H "X-API-Key: $WHEROBOTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "region": "aws-us-west-2",
    "name": "College Park roofs",
    "inputs": {
      "aoi": "s3://wherobots-examples/rasterflow/aois/collegepark.parquet",
      "start": "2023-01-01T00:00:00Z",
      "end": "2023-12-31T00:00:00Z",
      "model_recipe": "sam3-text-geometry",
      "text_prompt": ["roofs"],
      "confidence_threshold": 0.3
    }
  }'

# Repeat with the taskRunId from the response until state is no longer
# PENDING, SUBMITTED, RUNNING or CANCELLING.
curl "https://api.cloud.wherobots.com/task-runs/<taskRunId>" \
  -H "X-API-Key: $WHEROBOTS_API_KEY"

Run states

A run starts as PENDING, and is still in progress while its state is PENDING, SUBMITTED, RUNNING or CANCELLING. In the Python SDK, run.is_active is True for exactly those states. When a run stops, read its state:

SUCCEEDED: results holds the output URI.
Any other final state: error_message says why.

A run’s state can lag the run by up to two minutes, so poll every 30 seconds or so rather than in a tight loop. If you pass inputs that don’t match the task’s input schema, the API rejects the run with a 400 error before anything is launched or billed.

Task run results

When a run succeeds, results holds one output URI, named by the task:

Output	Tasks	What it points to
`mosaic_index_uri`	`build_mosaics`, `build_gti_mosaics`, `predict_mosaic_recipe`, `run_mosaic_inference`, `run_embedding_recipe`, `run_mosaics_change`	A mosaic index: a GeoParquet file whose `location` column lists the Zarr stores the task wrote.
`vector_results_uri`	`predict_mosaic_geometries_recipe`, `predict_mosaic_geometries`, `vectorize_mosaic`	A directory of GeoParquet files, or null when no features were produced.
`output_uri`	`build_zarr_multiscales`, `run_cog_inference`, `run_cog_embedding_recipe`	The store or files the task wrote.

To download an output from outside Wherobots, see Download a task run’s results.

Areas of interest

For mosaic builds, inference recipes, and mosaic change detection, pass the area of interest in aoi. The value can be an S3 URI of a GeoParquet or GeoJSON file, or a polygon or multipolygon WKT string with longitude/latitude coordinates in EPSG:4326. You do not need to upload a file to use inline WKT. For mosaic builds with inline WKT, also supply target_crs for the output grid.

Find a task’s inputs and outputs

Each task describes itself. With the Python SDK, wb.tasks.get(...) returns its description, input_schema, output_schema and examples:

task = wb.tasks.get("build_zarr_multiscales")
print(task.description)
print(task.input_schema["properties"])
print(task.output_schema)
print(task.examples[0].inputs)

wb.tasks.list() lists every task your Organization can run. The Tasks API reference documents the endpoints these calls use, including Get a task and List tasks. It doesn’t list each task’s inputs: those come from the task itself, in the inputSchema that Get a task returns, so they always match what the task accepts.

Region

Pass region="aws-us-west-2" (or "region": "aws-us-west-2" with the REST API) on every run. Without it, the run uses your Organization’s default region.

During Public Preview, RasterFlow is available in aws-us-west-2. If you’re interested in running RasterFlow in another region, contact Wherobots.

​Run a task

​Run states

​Task run results

​Areas of interest

​Find a task’s inputs and outputs

​Region

Run a task

Run states

Task run results

Areas of interest

Find a task’s inputs and outputs

Region