When an enterprise customer asks whether they can export their audit logs, the question behind the question is rarely "can I get a file." Any system can produce a file. Their security and compliance teams are asking something harder: can we hand this export to an auditor, a regulator, or opposing counsel, and have it hold up when someone has a reason to doubt it.

A CSV or JSON dump from a typical logging stack does not clear that bar. It is a file generated by the vendor, from a database the vendor controls, with timestamps from a clock the vendor can set. Nothing inside the file proves it is complete. Nothing proves a row was not edited, reordered, or quietly removed before the export ran. The auditor is being asked to trust the exporter, which is precisely the thing an audit exists to avoid.

This guide is about exporting audit logs in a form that does not require that trust. The mechanics are straightforward, you paginate an API and write the results to a file. The difference is in what each record carries: a per-tenant Ed25519 signature applied when the event was written, and a gapless sequence number that makes a missing record detectable. The export becomes evidence that verifies itself, instead of a document that depends on your good word.

Strip away the format debate and three concrete requirements remain. They map almost exactly to what an auditor checks.

Completeness. The export has to represent every event in the requested scope, with a way to detect if any are missing. "Here is a CSV" tells the auditor nothing about what is not in the CSV. A gap has to be detectable from the data itself, not taken on faith.

Integrity. Each record has to be provably unchanged since the moment it was created. Not "we have strict database permissions," that is a statement about your operational controls, which the auditor would then have to audit. The record itself has to carry the proof.

Portability. The auditor has to be able to verify the export without access to your systems and without trusting you or your vendor. If verification requires logging into your dashboard or believing your assurances, it is not independent verification.

Most audit-log exports satisfy none of these. They are point-in-time snapshots whose trustworthiness collapses to "the vendor says so." The rest of this guide walks through producing an export that satisfies all three.

On Invoance, an audit event is signed the instant it is recorded, not when it is exported. When you POST an event to the audit API, the backend assigns it the next sequence number for that organization, canonicalizes it, hashes the canonical bytes, and signs the result with your tenant's own Ed25519 private key. The signature and the hash are stored on the row alongside the data.

Two properties fall out of this. First, every record is independently verifiable for as long as you keep it, the proof travels with the data, so a record pulled out of the system years later still verifies against your published public key. Second, the sequence number is gapless and assigned in order, so a missing record leaves a hole that anyone can see.

That is why "export" here is not a special feature you have to wait for. The records are already proof-carrying. Exporting them is reading them out, and because each one is signed and sequenced, the file you produce is evidence the moment it lands on disk.

The export mechanism is the audit query endpoint, GET /v1/audit/events, called with an API key that holds the audit:read scope. It returns events newest-first and uses keyset pagination, so you page through an arbitrarily large log without the skips and duplicates that offset-based paging suffers under concurrent writes.

You scope the export with query parameters: org_id is required, and you can narrow by occurred_after and occurred_before (RFC3339 timestamps), by action (a comma-separated allowlist), by actor_id, and by target_id. limit defaults to 50 and caps at 100 per page. Each response carries an events array and a next_cursor; when next_cursor comes back null, you have reached the end of the range.

The loop is the whole export: call the endpoint, write the events, and if next_cursor is set, call again with cursor set to that value. Keep going until it is null.

In practice you wrap that one call in a loop and stream the results to a file. NDJSON, one JSON object per line, is the friendliest format to hand an auditor: every line is a complete, independently verifiable record, and the file streams without ever holding the whole log in memory.

The pattern below is the entire export. It writes each page as it arrives and follows next_cursor until the API reports there is nothing left. The same shape works in any language, the logic is request, append, advance the cursor, repeat.

A signed export is only worth something if the recipient can check the signatures, so the audit API exposes verification as a first-class endpoint. GET /v1/audit/events/{id}/verify takes a single event, rebuilds the exact canonical bytes that were signed from the stored columns, recomputes the hash, and checks the Ed25519 signature against your tenant's registered public key. Not the key stored on the row, the key pinned in your tenant record, which is what makes a forged or swapped key fail rather than pass.

The response is unambiguous: valid is a boolean, reason names the failure when valid is false (for example payload_hash_mismatch), and the body echoes the schema, the payload_hash it computed, and key_source so the verifier knows exactly which key was used.

For an export, you run this across the file. A practical pattern is to verify every record on the way out, or verify a random sample plus every record above a sensitivity threshold, and attach the results to the export as a manifest. Either way the point stands: the auditor does not have to take the file on faith, and neither do you. Because the signature is Ed25519 and your tenant's public key is publishable, a recipient can also verify the whole export offline, with a standard crypto library, without ever calling Invoance.

Verification tells you each record you exported is authentic. It does not, on its own, tell you that you exported all of them. Completeness is a separate question, and it is the one a CSV can never answer.

This is what the gapless sequence number is for. Every audit event for an org carries a strictly increasing seq, assigned in a single transaction at write time. GET /v1/audit/orgs/{id}/integrity walks that sequence and reports whether it is contiguous: you get last_seq, a count, a contiguous boolean, and a gaps array listing any missing ranges. A complete export covers a contiguous block of sequence numbers; a hole in the middle is mathematically visible.

Run the integrity scan as part of the export and record its result. Together with the per-record signatures, it lets you make a precise, defensible claim: these are records 1 through last_seq for this organization, each one signed and unaltered, with no gaps.

Enterprise audit-log requirements almost always include a retention term, "logs retained for N years, available on request." On Invoance, retention is set per organization with PUT /v1/audit/orgs/{id}/retention, and the window you can request is bounded by your plan tier. Higher tiers unlock longer retention; the API clamps any request to your plan's cap rather than silently accepting a value it cannot honor.

Behind the endpoint, recent events stay hot in Postgres for fast querying, and older events are tiered to dedicated cold object storage as compressed, signed segments. The signature and sequence number travel with the data into cold storage, so an event exported from a three-year-old cold segment verifies exactly the same way as one written this morning. Retention changes where a record lives, never whether it can still be proven.

Everything above works against the live API today. Two higher-level conveniences are on the roadmap, and both are wrappers around the same signed records, not new sources of truth.

One-call bulk export will let you request an entire range as a single job: submit a scope and a format (CSV or NDJSON), poll for completion, and download one file covering both hot and cold storage, without writing the pagination loop yourself. SIEM streaming will push each event to a destination such as a webhook or Splunk as it is written, so audit events land in your customer's existing security tooling in near real time.

Until those ship, the paginate-then-verify pattern in this guide is the supported path, and it is the exact mechanism the bulk-export job will automate. Nothing about the records changes, the convenience layer is the only thing being added.

The fastest way to evaluate this is to produce a real export against a free account. Sign up, create an audit organization, and mint an API key with the audit:read and audit:write scopes. Write a handful of events with the ingest endpoint, then run the export loop above, you get back records that are actually signed with your tenant's own key, with a real sequence and a real integrity scan.

The records your free account produces verify through the same endpoints and against the same kind of per-tenant key that back Compliance and Enterprise accounts. The infrastructure is identical; the plan tiers change limits and retention, not whether a record can be proven.

If you are working through an enterprise security review, that free export is the asset to hand over. Give the reviewer an exported record and the verify endpoint, let them confirm the signature and the contiguous sequence themselves, and the trust question stops being a conversation and becomes a demo. That is usually what unblocks the deal.