How-to guide
Export and verify the audit log
Export audit rows for a date range, check that the hash chain is intact, and compare an export with a later one.
This guide shows how to export your audit log and check that no row was changed or removed. A reviewer or an admin can export. Only an admin can run the full check. A key with the decide scope can export too.
Before you start#
Each audit row stores a hash, which is a fixed-length fingerprint of the row and of the row before it. If someone changes or removes a row, the fingerprints after it no longer match. The log is one chain for the whole platform. You see only the rows of your own organization. For the idea behind it, read How the audit chain works.
Export a date range#
- Choose a range of 92 days or fewer.
- Send the request:
curl "https://api.example.test/api/v1/audit/export/?from=2026-11-01&to=2026-11-14" \
-H "Authorization: Bearer yq_live_..." -o audit-2026-11-01_2026-11-14.json- Save the file with your records.
The export has at most 20,000 rows, in order of seq, the row number. If rows in the answer is 20,000, the range was cut. Export a shorter range.
An export is itself an audit event. Yaqeen records who took it and how many rows it held.
Read the answer#
{
"from": "2026-11-01",
"to": "2026-11-14",
"rows": 1,
"chain_intact": true,
"first_prev_hash": "9c1f...",
"last_row_hash": "4be0...",
"events": [
{
"seq": 1204,
"id": "6a1d2e3f-0000-4000-8000-0000000000a1",
"at": "2026-11-03T09:12:44.512300+00:00",
"actor": "reviewer.example",
"action": "hold.approved",
"subject_type": "hold",
"subject_id": "e1b2c3d4-0000-4000-8000-000000000001",
"payload": { "from": "recommended", "to": "approved" },
"prev_hash": "9c1f...",
"row_hash": "77d3..."
}
]
}| Field | Meaning |
|---|---|
chain_intact | true when Yaqeen recomputed the whole chain at the moment of the export and found no break. |
rows | How many events the answer holds. |
first_prev_hash | The prev_hash of the first row. It is null when the range is empty. |
last_row_hash | The row_hash of the last row. It is null when the range is empty. |
events | The rows. actor is a username, or null when no person caused the row. |
If chain_intact is false, run the full check below and tell your Yaqeen contact.
Run the full check#
An admin sends GET /api/v1/ops/audit-verify/. Yaqeen walks the whole log, recomputes every hash and compares the chain head with the last row.
{ "intact": true, "breaks": [] }When a break exists, each item has the row number and a reason:
| Reason | Meaning |
|---|---|
previous hash does not match the row before | A row between these two was changed or removed. |
row content does not match its hash | The content of this row was changed. |
chain head does not match the last row (rows removed or added) | Rows were removed from the end, or added outside the chain. |
Yaqeen also runs this check every day, and alerts when the chain breaks if an alert channel is set up.
Compare with an export you saved#
Your saved export is a copy that Yaqeen cannot change. To check the log later:
- Export the same date range again.
- Match rows by
seq. - For each row, compare
row_hashwith your saved copy.
Every pair must be equal. A different row_hash, or a row missing from the new export, means the log changed after you saved your copy. Tell Yaqeen at once, with both files.
Your export holds only your organization's rows, so the prev_hash of a row can point to a row that is not in it. Compare row_hash values instead of following the links in your export.
Read events without exporting#
GET /api/v1/audit/ lists events, newest first, 25 at a time. Filter with subject_type and subject_id, for example ?subject_type=hold&subject_id=e1b2c3d4-0000-4000-8000-000000000001. See Rate limits and pagination.
If it does not work#
- You get
400 bad_range: sendfromandtoas dates such as2026-11-01, withtonot beforefrom, and at most 92 days apart. - You get
403: the export needs the reviewer or admin role. A key with onlyreadacts as a reviewer but can only send GET, HEAD and OPTIONS, so areadkey is refused when it asks for the export withPOST. - The export is empty: no event of your organization falls in the range.
Next steps#
- How the audit chain works: why a change shows up.
- Roles and permissions: who can read the log.
- Go live checklist: run the check before you go live.