YaqeenDocs
Back to Yaqeen

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#

  1. Choose a range of 92 days or fewer.
  2. Send the request:
bash
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
  1. 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#

json
{
  "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..."
    }
  ]
}
FieldMeaning
chain_intacttrue when Yaqeen recomputed the whole chain at the moment of the export and found no break.
rowsHow many events the answer holds.
first_prev_hashThe prev_hash of the first row. It is null when the range is empty.
last_row_hashThe row_hash of the last row. It is null when the range is empty.
eventsThe 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.

json
{ "intact": true, "breaks": [] }

When a break exists, each item has the row number and a reason:

ReasonMeaning
previous hash does not match the row beforeA row between these two was changed or removed.
row content does not match its hashThe 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:

  1. Export the same date range again.
  2. Match rows by seq.
  3. For each row, compare row_hash with 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: send from and to as dates such as 2026-11-01, with to not before from, and at most 92 days apart.
  • You get 403: the export needs the reviewer or admin role. A key with only read acts as a reviewer but can only send GET, HEAD and OPTIONS, so a read key is refused when it asks for the export with POST.
  • The export is empty: no event of your organization falls in the range.

Next steps#

Up Down to moveEnter to openEsc to close