Generate Audit Trail Export
Enqueue an asynchronous render of the audit-trail export for a DDS record's current version. One call produces all three deliverables in the same job:
- the print-ready PDF โ Download Audit Trail PDF
- the self-contained interactive HTML (same sections as the PDF, plus a live plot map) โ Download Audit Trail HTML
- the full export package (ZIP: PDF + interactive HTML +
report.json+ chunkedgeojson/part files + every stored attachment) โ Download Audit Trail Package
Returns 202 with a dds_record_task envelope
(operation: "generate_audit_trail_pdf") and a Location header pointing at
the task-status endpoint. The render runs on a dedicated Chromium worker;
poll Get Audit Trail Task
until status: "completed", then fetch a download link from either endpoint
above. Both share one content hash, so an unchanged version is neither
re-rendered nor re-zipped.
Send an empty body ({}).
โถGenerating a specific version
POST /regulations/eudr/audit-trail/:recordId/versions/:versionId/audit-trail
generates the export for a specific historical version instead of the current
one. Same request and response shape.
โถRe-requesting
You can only have one PDF being prepared at a time per version โ asking again
while one is still in progress returns 409. Once it finishes, you can ask
again; if the underlying data hasn't changed you get the existing PDF back
(the task reports cache_hit: true) without waiting for it to be re-built.
โถForcing a rebuild
Pass ?force=true to bypass the cache and re-render even when the data hasn't
moved the report's content hash. You rarely need this: editing the audit trail
(excluding/including a plot, editing a justification or override) already marks
the stored PDF stale and rebuilds it automatically โ see
Download Audit Trail PDF. force is for
cases where you want to guarantee a fresh render on demand.
You cannot rebuild a submitted version's PDF. Once a version has been
submitted to TRACES (or a submission is in flight), its PDF is the frozen
record of what was filed โ both a normal and a force=true request return
409. The submission flow produces that final PDF itself.
โถWhen the export is ready
Once the task is completed, its result describes all four artefacts:
| Field | Type | Description |
|---|---|---|
content_type | string | The PDF content type โ application/pdf |
size_bytes | int | Size of the PDF |
cache_hit | boolean | true when an existing render was reused (unchanged version) |
version_id | uuid | The version the export covers |
download_url | string | Path to fetch the PDF download link (Download Audit Trail PDF) |
package_content_type | string | The package content type โ application/zip |
package_size_bytes | int | Size of the ZIP package |
package_download_url | string | Path to fetch the package download link (Download Audit Trail Package) |
html_content_type | string | The HTML content type โ text/html; charset=utf-8 |
html_size_bytes | int | Size of the interactive HTML export |
html_download_url | string | Path to fetch the HTML download link (Download Audit Trail HTML) |
geojson_content_type | string | The GeoJSON content type โ application/geo+json |
geojson_part_count | int | Number of files the GeoJSON export is split into |
geojson_total_size_bytes | int | Sum of the parts' sizes |
geojson_dds_hash | string | The report fingerprint the parts were built from |
geojson_download_url | string | Path to fetch the GeoJSON download links (Download Audit Trail GeoJSON) |
download_url / package_download_url / html_download_url /
geojson_download_url are paths to the org-scoped download endpoints (they
return the short-lived signed URLs) โ not the signed URLs themselves.
โถThe GeoJSON block
The five geojson_* fields describe the TRACES-ready geolocation file โ
the one you upload to the EU portal when you file your own DDS. It is the
filing scope: included, compliant plots only. That is a different document
from the package's geojson/ entries, which cover every plot as evidence for
a competent authority. See
Download Audit Trail GeoJSON.
It is the only artefact that can be more than one file: TRACES caps a single
geolocation upload at 25 MB base64, so a large record is split into
geojson_part_count parts. Fetch every one.
The block is absent on a task that completed before this export existed.
The five fields above are the whole of what this endpoint reports about
it: the render job records a fuller per-part manifest internally, but it
is not exposed here. For per-part detail โ feature counts, base64 sizes,
the per-part ceiling โ use
Download Audit Trail GeoJSON, whose
manifest is the only one a client can read.
โถThe HTML block can lag
The three html_* fields appear only once the export exists. The HTML is
rendered last, as an additive step that can never fail the job, so for a
moment after the task first reports completed the block is simply absent โ
poll again and it appears. Its download endpoint answers 425 Too Early over
the same window. If the HTML render failed (which by design does not fail the
task), it stays absent while the PDF and package remain valid. Treat its
presence, not the task status, as the signal that the export is ready.
โถA render that stops without reporting
The render job flips its task to failed from its own error handler, which a
hard crash โ an out-of-memory, a killed container โ never reaches. Nothing
writes the row after that, so the task would otherwise report processing
for ever and a poller would wait on it until its own timeout.
A generate_audit_trail_pdf task still processing 15 minutes after it
was created is therefore reported as failed, with an error_message saying
the worker stopped without reporting a result. Ask for a new render.
Fifteen minutes is not a guess: it is the hard limit the renderer job runs under, so a render still going past it has already been stopped.
The window starts when the task is created, so time spent queued counts
toward it. On a busy queue a failed verdict can therefore reflect a long
wait rather than a dead worker โ asking for a new render is the right
response either way.
The bound applies to this operation only. A version cut or a submit runs elsewhere, with a limit measured in hours, and is never aged out.
โถStatus codes
| Code | When |
|---|---|
202 | Accepted โ the export is being prepared (task returned) |
404 | No such DDS record (or version) for this caller |
409 | An export is already being prepared for this version, or the version has been submitted and its export is frozen |
500 | Couldn't start preparing the export โ try again |
Required scope:
eudr:write