Skip to main content

​
Async Tasks and Workflows

Long-running operations (for example shading and energy model runs) are executed asynchronously.

​
Async Pattern

  1. Client submits a request to an async endpoint.
  2. API returns 200 with a taskId (and often created resource IDs).
  3. Worker processes the task.
  4. Client polls /tasks/{task_id} until terminal status.

​
Task Lifecycle

Task statuses:
  • pending
  • queued
  • running
  • completed
  • failed
  • cancelled
Stages provide finer progress (initializing, processing, saving, etc.).

​
Polling Endpoints

​
Workflow Chains

Some operations create a parent workflow with child tasks.

​
Polling Example

Example response fields:
Treat task result payloads as task-type-specific. For final model outputs, fetch the created resource directly (for example /energymodels/{id}).
For saved energy-model reruns, the queued task still resolves back to the same /energymodels/{id} row. Rerun does not create a second energy-model resource.