List Ingestion Tasks
List all ingestion tasks for your organization.
βΆUse Cases
- View ingestion history.
- Monitor ongoing ingestion tasks.
- Build an ingestion management dashboard.
βΆFilters
Use filter[field]=condition:value to narrow results. See Query Parameters for full syntax.
filter[overall_status]=eq:stagedβ find tasks in a specific statusfilter[overall_status]=eq:completedβ find completed tasksfilter[overall_status]=eq:failedβ find failed tasksfilter[location_type]=eq:facilityβ narrow to one location type (facility,plot, orshed)filter[source_file]=eq:supply_chain_data.csvβ match the source filename
βΆSorting
Use ?sort= to order results (leading - = descending); the key is folded into the cursor so it composes with page[cursor]=. Any other key returns 400.
| Sort key | Meaning |
|---|---|
created_at | Task creation time. The default order is created_at ascending; ?sort=-created_at gives newest-first. Organization-composite-backed β O(page_size) at any depth for one organization. A parent organization without x-acting-as sorts every task in scope on each page. |
name | Task name (the caller-supplied label, falling back to the source filename). Unnamed tasks sort last (NULLS LAST) in both directions. Ascending (?sort=name) is organization-composite-backed β O(page_size) at any depth. Descending (?sort=-name) is not index-backed: NULLS LAST flips to NULLS FIRST on a backward index scan, so the planner falls back to a sort over your org's task count (same cost note as source_file / overall_status). |
source_file | Uploaded source filename. Accepted but not org-index-backed, so it costs a sort over your org's task count (fine at typical volumes, slower for very large orgs). |
overall_status | Task status. Same cost note as source_file. |
id | Task UUID. |
βΆPagination
Supports both page-number (offset) and cursor (keyset) modes β the same
page[size] knob and response envelope, differing only in how you
advance. Opt into cursor mode by passing ?page[cursor]= (empty value =
first cursor page); follow meta.next_cursor (echoed into links.next as
page[cursor]=) to walk the full list in O(page_size) at any depth.
- Cursor traversal requires an explicit
?sort=(the defaultcreated_at, idorder can't be safely resumed by keyset) β resuming a cursor without one returns400, and a malformed cursor returns400(not500). - Cursor responses carry
meta.total: null(noCOUNT(*)) β usemeta.has_next/meta.next_cursorto traverse. Page-number responses never emitmeta.next_cursor.
βΆQuery parameters
include=deforestationβ opt-in EUDR compliance roll-up. Attachesattributes.deforestationto each task in the response with plot counts (total_plots,compliant_plots,non_compliant_plots,unknown_plots) and area totals (total_area_ha,compliant_area_ha). The roll-up is batched server-side, so a page of N tasks costs one extra query. Works in both the paginated JSON response andAccept: application/x-ndjsonstreaming (rows flush in bounded chunks). Unknown include values return 400VALIDATION_ERROR. See Query Parameters β Per-endpoint includes.
βΆDegroup (?degroup=true)
?degroup=true)By default each ingestion task is one row. Pass ?degroup=true to expand a task whose location_type is facility or shed into one row per distinct resolved location (its staged_location). plot (and any other) tasks are returned unchanged β a single row β because a plot upload can resolve to thousands of locations.
Each expanded row carries a new attribute:
staged_location_idβ the resolved location this row represents. Populated only under?degroup=true. The taskidrepeats across the sibling rows of the same task, so the unique key becomes(id, staged_location_id). It isnullfor a degroupedfacility/shedtask that has not resolved any location yet, and forplot/other tasks; the field is absent entirely whendegroupis off.
Behaviour notes:
include=deforestationgrain follows the row. A degroupedfacility/shedrow reports its own location's catchment roll-up (per-staged_location), not the whole task's aggregate. Aplottask's single row (and any non-degrouped row) keeps the task-level roll-up. So the compliance numbers on a facility row match that one facility, whiledegroup=falseshows the task-wide total.- The task-level roll-up describes CURRENT records. Since EPO-2331 it counts only the plots a record that still holds currency owns, so a plot whose record a later upload superseded is excluded.
filter[compliance]reads the same numbers, so the filter and the displayed block always agree. One consequence: a task's numbers can change without the task changing, because a later upload of one of its locations moved which record is current. collection_idsfollow the row too. A degroupedfacility/shedrow lists only its own supply-shed collection hash(es), rather than every collection the task produced (which each sibling row would otherwise repeat). Non-degrouped rows (andplottasks) keep the task-widecollection_ids.- Pagination.
meta.totalcounts the expanded rows in offset mode. Offset and cursor (page[cursor]=) pagination andAccept: application/x-ndjsonstreaming are all supported. Under cursor mode the composite(sortβ¦, id, staged_location_id)key is carried in the cursor payload, so keyset traversal resumes correctly across a task's sibling rows;meta.totalisnullon cursor responses (walk withmeta.next_cursor). - To list the individual locations themselves (one row per facility/shed/plot, with their own filters and geometry), use the Locations endpoints instead β
degroupis a convenience on the task list, not a replacement for the locations resource.
Required scope:
ingestions:read