4 Process Metrics

Step 4: Process Metrics

Trigger deforestation and emissions batch processing on the validated entities. Uses filter[assets.task_id] to select which entities to process.

The task must be in staged status before processing can be triggered.

What this step does

It kicks off the geospatial metric runs (deforestation, emissions) over the staged entities selected by the filter. The filter[assets.task_id] query scopes the run to the task from Step 1; you can narrow it further (e.g. filter[assessments.core.confidence_level]=eq:high, or by tags) to process only a subset. The response returns a task id captured into {{process_task_id}} โ€” this is the handle you poll and read results against from here on.

Why it's needed

Staging validates and normalises locations but does not compute any metrics โ€” deforestation risk, emissions, and the facility/shed/plot derivation only happen when you trigger this call. Processing a facility here is what resolves its supply shed and the plots beneath it, so without this step there is nothing for the locations and metrics endpoints (Steps 6aโ€“6e) to return. Requiring staged first guarantees the entities have been validated before you spend compute on them.

Why it's a separate call (scope selection)

Splitting process from upload is what lets you be selective: after reviewing Step 3 you decide which entities are worth the metric run rather than paying for all of them. The filter on this call is that selection. If you never need that choice โ€” trusted, known-good data โ€” fold the metrics into the upload with Quick Ingestion and skip this step entirely.

Request

PUT /ingestions/assets?filter[assets.task_id]=eq:{task-id}

Query filters:

FilterDescription
filter[assets.task_id]Task ID from Step 1
filter[assessments.core.confidence_level]Optionally limit to eq:high entities
filter[tags]Filter by tag name

Body:

FieldTypeDescription
metricsstring[]Metrics to compute: deforestation, emissions
tagsstring[]Optional additional tags to apply
end_datestringEnd date for zonal statistics (YYYY-MM-DD). Defaults to today.

Frontend Usage

  • Store data.id as the process task ID for polling
  • Show "Processing 42 entities" status message
  • The total count tells the frontend how many entities will be processed
  • Begin polling Step 5 to track progress

Next Step

โ†’ Step 5: Check Processing Status (GET /ingestions/:id/summary)