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 |
|---|---|
| 01 | POST /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. |
| 02 | Polls GET /ingestions/{task_id} until the first task is terminal. |
| 03 | POST 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. |
| 04 | Polls 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. |
| 05 | GET /ingestions/assets/latest โ one row per location, and the row reports superseded_count: 1. Captures latest_records_row_id and latest_records_location_id. |
| 06 | GET /ingestions/assets/latest/{row_id}/history โ the whole lineage, the current record leading, each entry flagged is_live. |
| 07 | GET /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 resourceid. Step 06 addresses the history with it.latest_records_location_idโ set by step 05, for cross-checking the history'smeta.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
end_date in step 03Currency 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.