> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wherobots.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run RasterFlow Tasks

> Learn how to run RasterFlow tasks through the Tasks API.

Every RasterFlow workflow is a task in the [Tasks API](https://docs.wherobots.com/api-reference/tasks/run-a-task.md). 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](https://pypi.org/project/wherobots-python-sdk/) uses your Wherobots credentials. Anywhere else, set a [Wherobots API key](https://docs.wherobots.com/get-started/wherobots-cloud/api-keys.md) in `WHEROBOTS_API_KEY`. The SDK needs Python 3.11 or later.

```python Python theme={"system"}
# 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)
```

```bash API theme={"system"}
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](https://docs.wherobots.com/develop/rasterflow/rasterflow-storage-integration.md#download-task-run-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`:

```python theme={"system"}
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](https://docs.wherobots.com/api-reference/tasks/run-a-task.md) documents the endpoints these calls use, including [Get a task](https://docs.wherobots.com/api-reference/tasks/get-a-task.md) and [List tasks](https://docs.wherobots.com/api-reference/tasks/list-tasks.md). 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.

> [!NOTE]
>
> During Public Preview, RasterFlow is available in `aws-us-west-2`. If you're interested in running RasterFlow in another region, [contact Wherobots](https://wherobots.com/contact/).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.