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 status
  • filter[overall_status]=eq:completed β€” find completed tasks
  • filter[overall_status]=eq:failed β€” find failed tasks
  • filter[location_type]=eq:facility β€” narrow to one location type (facility, plot, or shed)
  • 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 keyMeaning
created_atTask 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.
nameTask 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_fileUploaded 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_statusTask status. Same cost note as source_file.
idTask UUID.

See Query Parameters β†’ Client-controlled sort.

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 default created_at, id order can't be safely resumed by keyset) β€” resuming a cursor without one returns 400, and a malformed cursor returns 400 (not 500).
  • Cursor responses carry meta.total: null (no COUNT(*)) β€” use meta.has_next / meta.next_cursor to traverse. Page-number responses never emit meta.next_cursor.

See Query Parameters β†’ Pagination.

Query parameters

  • include=deforestation β€” opt-in EUDR compliance roll-up. Attaches attributes.deforestation to 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 and Accept: application/x-ndjson streaming (rows flush in bounded chunks). Unknown include values return 400 VALIDATION_ERROR. See Query Parameters β€” Per-endpoint includes.

Degroup (?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 task id repeats across the sibling rows of the same task, so the unique key becomes (id, staged_location_id). It is null for a degrouped facility/shed task that has not resolved any location yet, and for plot/other tasks; the field is absent entirely when degroup is off.

Behaviour notes:

  • include=deforestation grain follows the row. A degrouped facility/shed row reports its own location's catchment roll-up (per-staged_location), not the whole task's aggregate. A plot task'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, while degroup=false shows 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_ids follow the row too. A degrouped facility/shed row 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 (and plot tasks) keep the task-wide collection_ids.
  • Pagination. meta.total counts the expanded rows in offset mode. Offset and cursor (page[cursor]=) pagination and Accept: application/x-ndjson streaming 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.total is null on cursor responses (walk with meta.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 β€” degroup is a convenience on the task list, not a replacement for the locations resource.

Required scope: ingestions:read