Statuses

pending ──→ validating ──→ staged ──→ processing ──→ completed
                              │            │
                              │            ├──→ completed_with_errors  (some entities failed/skipped)
                              │            ├──→ skipped  (all entities skipped)
                              │            └──→ failed   (processing error)
                              │            ↑
                              │            └── retry: PUT /ingestions/assets
                              │                       ?filter[assets.task_id]=eq:{id}
                              │
                              └──→ failed  (validation error / no entities found)

A failed task keeps the rows it staged, so a retry does not need the file again. Send the same reprocess call you would use on a staged task:

PUT /ingestions/assets?filter[assets.task_id]=eq:{asset_task_id}
Content-Type: application/json

{
  "metrics": ["deforestation"]
}

Check the id in the response, and poll that one. The task is reused only from staged and failed. From any other status the call still answers 202, but it creates a new task and returns the new id, because the original cannot be reclaimed: processing and validating mean a run is already in flight, completed and completed_with_errors mean the work is done, pending has nothing staged yet, and skipped produced no usable rows.

Both outcomes are a 202, so tell them apart from the response rather than assuming:

A retry resumes work already submitted rather than repeating it, so a batch that was part-way through is not recomputed or re-billed from scratch. If none of the staged rows survive (a task that failed before its batch was submitted has its rows cleared), the call answers 400 with No staged assets match the given filters — re-ingest from the file in that case.

Use filter[overall_status] on GET /ingestions/tasks to find tasks in specific states:

pending ──→ staged ──→ processing ──→ completed
               │            │
               │            ├──→ skipped  (batch skipped)
               │            └──→ failed   (batch error)
               │
               └──→ skipped  (no location or no commodity)

Entities are skipped (not failed) when:

• No location found — the geocoder could not resolve the input address/coordinates to a valid location.
• No commodity type — the entity's commodity type is null or unknown, which is required for metrics.
• Batch skipped — the analysis engine determined no processing was needed (e.g. location already covered by a recent analysis).

Use filter[status] on GET /ingestions/assets/:id to focus on specific entities:

1. Poll GET /ingestions/:id/summary at a regular interval (e.g. every 3–5 seconds).
2. Compute progress as: (completed + skipped + failed) / total.
3. Stop polling when overall_status is completed, skipped, or failed.
4. Display by_status counts to show users how many entities are in each phase.

Total: 42 entities
████████████████████░░░░░  28 completed, 12 processing, 1 skipped, 1 failed