Latest Records

End-to-end recipe for the question customers ask first: "I uploaded this supplier list again โ€” why do I now see every facility twice?"

You do not. You see two records of one facility, which is what an uploaded record is. This workflow uploads a facility file, uploads it again with a later monitoring window, and then shows the same data at both grains: GET /ingestions/assets returns both records, GET /ingestions/assets/latest returns one row, and that row names the record it replaced.

Use it to see supersession happen rather than to read about it. For the concepts, see Record Supersession.

Steps

#What it does
01POST /ingestions/assets with location_type: facility, end_date: 2024-12-31, and metrics: ["deforestation"] โ€” folding processing into the upload so the task reaches completed and its records get stamped. The docs UI's Upload tab drives the byte PUT off meta.client_actions[0]. Captures latest_records_task_id.
02Polls GET /ingestions/{task_id} until the first task is terminal.
03POST the same facilities again with a later end_date of 2025-12-31 and metrics: ["deforestation"] (same currency-stamp requirement as step 01), plus force: true to bypass the duplicate-upload guard. Captures latest_records_second_task_id.
04Polls the second task until terminal. The currency stamp is written as the pivot rows are inserted, so this is the barrier before any deduped read.
05GET /ingestions/assets/latest โ€” one row per location, and the row reports superseded_count: 1. Captures latest_records_row_id and latest_records_location_id.
06GET /ingestions/assets/latest/{row_id}/history โ€” the whole lineage, the current record leading, each entry flagged is_live.
07GET /ingestions/assets/latest?include=metrics.deforestation โ€” the metric attached to the row's location, for the current record only.

Variables exchanged

  • latest_records_task_id โ€” set by step 01, the first upload.
  • latest_records_second_task_id โ€” set by step 03, the re-upload.
  • latest_records_row_id โ€” set by step 05; the record handle, not the resource id. Step 06 addresses the history with it.
  • latest_records_location_id โ€” set by step 05, for cross-checking the history's meta.location_id.
  • latest_records_poll_retries / latest_records_second_poll_retries โ€” bound the two polling steps.

The upload steps need the docs UI

Steps 01 and 03 post JSON and receive a signed URL; the file bytes travel separately as a PUT, which the docs UI's Upload tab performs from meta.client_actions[0]. That is how every workflow in this collection uploads, and it means the two upload steps do not run headless.

For the same sequence as an automated check that does run headless, see the Latest Records Dedupe suite under Tests/Emulated/, which uploads with multipart-form instead.

Why a later end_date in step 03

Currency is not "the newest upload". It follows the six-key EPO-1089 precedence, and monitoring_end is key 2 โ€” so a re-upload carrying a later end_date takes currency at that key.

Re-uploading with the same window would not reliably supersede anything: keys 1 and 3 prefer a record whose location already has metric results and assessments, which the earlier record may have and the new one may not. That is deliberate, and it is why this workflow moves the window rather than just uploading twice.

Both dates are Dec 31 of a prior year on purpose. end_date accepts that form, or any date in the current year up to today โ€” so a mid-year date like 2026-06-30 is valid this year and rejected from 1 January onwards. Two prior-year year-ends keep the workflow runnable indefinitely.