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 ask the API for the records and write them to a file, or let the export endpoint build the file for you. 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 an export from Invoance is evidence rather than a snapshot. Whether you request a packaged file or pull events through the API, every record is already signed and sequenced, so what you hand over verifies the moment it lands.

For a point-in-time export, the audit API does the assembly for you. POST a scope and a format to /v1/audit/exports and Invoance queues a job, streams every matching event from both hot storage and cold archival into a single file, and returns a download link when it is ready. One request covers the whole range, including events already tiered to cold storage, with no pagination on your side.

The body takes organization_id, a format of csv or ndjson, and an optional filters object with the same fields the query API accepts: actions, actor_id, target_id, range_start, range_end. The call returns an export id with a status of pending.

You then poll GET /v1/audit/exports/{id} until status is ready. The ready response carries a row_count and a download_url, a presigned link valid for 24 hours. CSV exports are written with spreadsheet formula-injection protection, so a cell that begins with =, +, or @ cannot execute when an auditor opens the file in Excel.

If you would rather stream the export yourself or fold it into a pipeline, page the audit query endpoint directly. GET /v1/audit/events, called with an API key that holds the audit:read scope, 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: organization_id is required, and you can narrow by range_start and range_end (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: it echoes the from/to window it scanned, last_seq, a count and the expected 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.

Security teams usually want audit events flowing into their own tooling continuously, not just on request. Attach a streaming destination to an org with POST /v1/audit/orgs/{id}/streams. The supported destination today is a generic HTTPS webhook, which covers most SIEM and log pipelines; named connectors such as Splunk HEC are on the connector roadmap.

Every delivery is signed with an HMAC secret carried in the X-Invoance-Signature header. That secret is returned exactly once, when you create the stream, so the receiver can confirm a payload came from Invoance and was not altered in transit. A new stream starts at the org's current sequence and forwards events from the moment you connect it rather than replaying history, which is how SIEM pipelines expect to behave.

The destination is checked against server-side request forgery before it is accepted: it must be HTTPS and cannot resolve to a private, loopback, link-local, or cloud-metadata address. For a product whose whole point is trust, an audit stream must never become a way to probe an internal network.

Sometimes the cleanest export is not a file, it is a link. POST /v1/audit/portal_sessions mints a one-time link to a hosted, read-only viewer scoped to a single org. You give it to an auditor or a customer's security reviewer and they browse the log, filter by action, actor, and date, open any event, and verify its signature from the browser, with no Invoance account and no access to anything else in your tenant.

The link is single-use and must be opened within five minutes; once opened it becomes a read-only session whose length you choose, from one minute up to 24 hours. The viewer can export the filtered view to CSV or JSON itself, so the reviewer can take a copy without you running anything. Pass an intent of audit_logs for the log viewer, or log_streams to let a customer manage their own webhook destinations.

Two things are deliberately not claimed yet, and it is worth being exact about them with a security team.

First, more named SIEM connectors. The generic signed webhook ships today; dedicated connectors such as Splunk HEC are still on the roadmap, so a destination that needs a vendor-specific format sits behind the webhook for now.

Second, and more important: the integrity scan proves that nothing in the middle of the log was changed or removed, but detecting truncation of the very newest events requires a signed checkpoint of the sequence head, which is not shipped yet. That is exactly why Invoance describes these logs as signed and verifiable rather than immutable. Per-event signatures and a gapless sequence are strong, provable claims today; a tamper-proof head that also rules out tail-truncation is the next step. Claiming only what the cryptography supports today is the entire point of a trust product.

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 request an export with the calls 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.