Get Ingestion Task

Get the details and current status of a specific ingestion task.

Use Cases

  • Poll for task completion after uploading a file.
  • Check the current processing stage of an ingestion (validating, geocoding, matching, complete).

Status lifecycle

The overall_status field tracks the current processing stage:

  • pending โ€” task created, processing has not started.
  • processing โ€” file is being stored and prepared.
  • validating โ€” normalization and validation steps are running.
  • staged โ€” locations validated and staged, ready for processing.
  • completed โ€” processing finished successfully.
  • failed โ€” processing failed (see error_message; for a duplicate upload, also duplicate_of_asset_task_id).

Task attributes

Alongside overall_status, source_file, and tags, every task carries:

  • name โ€” human-friendly task name. Caller-supplied at creation, or derived from the tags (joined with , ) falling back to the source filename.
  • description โ€” free-form caller-supplied notes; null when none was set.
  • location_type โ€” facility, plot, or shed. Reconciled to the type detected in the uploaded file once the task reaches staged, so it may differ from the value originally requested.
  • error_message โ€” the human-readable reason. Populated when overall_status is failed or skipped, and on a staged task the credit check refused, as <code>: <reason> (e.g. LOCATION_ALREADY_HELD, INSUFFICIENT_CREDITS); a held-location refusal lists the first five held keys and counts the rest. null otherwise.
  • duplicate_of_asset_task_id โ€” present only when this upload was rejected as a duplicate (signed-URL flow). The task is failed and this is the id of the earlier completed task whose results to use instead. Re-submit with force: true to override. See Ingest Assets โ€” Duplicate uploads.
  • tags โ€” the tags supplied at creation, echoed verbatim. Includes any namespace:{Column Header} per-row templates; these are expanded against each row at ingestion (they are not pre-expanded here). See Ingest Assets โ€” Per-row tags from columns.

Query parameters

  • include=deforestation โ€” opt-in EUDR compliance roll-up. Adds attributes.deforestation to the response with plot counts (total_plots, compliant_plots, non_compliant_plots, unknown_plots) and area totals (total_area_ha, compliant_area_ha). Only meaningful once the task's deforestation processing has completed; unknown include values return 400 VALIDATION_ERROR. See Query Parameters โ€” Per-endpoint includes.

Required scope: ingestions:read