Log export

A log export is the drain’s offline twin. The same rows go through the same event builder and the same scrubber as a log drain; instead of being pushed at a destination you own, they are written as gzipped NDJSON and handed back as signed, expiring links. Use it when you have no collector, or when you need a window that predates the drain — a drain copies what happens next, and an export reads what already happened.

An export applies Lua’s built-in scrubbing and your organization’s own scrub rules.The built-in rule classes — builtin, lua-token, vendor-key — run unconditionally on every record, exactly as they do on a drain delivery. On top of them, an export applies the union of the rules you added yourself across your organization’s active drains, so a value a drain would mask as [redacted:org:<your rule id>] carries the same mask in an export file.The union, not one drain’s list, because a rule is configured per drain and an export is organization-wide: the only answer that cannot under-redact is every rule the organization has asked for anywhere. “Active” means every drain that is not disabled and not deleted — a paused drain’s rules still count. Masking is only ever added: an organization with no drain rules downloads byte-identical files either way.It may not be enabled on your deployment yet. Where it is not, an export applies the built-in classes alone, and a value only an organization rule would have caught is in the files in the clear. counts.orgScrubHits on the finished job says which of the two you got: it is absent when no organization rule ran.

These routes are organization-scoped and need logs:read. The base URL, bearer authentication, and the error envelope are on the REST API overview; lua logs export is the same surface from a terminal.

Exports are switched on for a deployment as a whole. While they are off, both routes answer 404 — the resource does not exist rather than being forbidden. It may not be enabled on your deployment yet.

Scopes

Operation	Scope
Start an export, read a job	`logs:read`
`includeContent: true`	`logs:read` and `logs:manage`

logs:manage is sensitive: a wildcard such as logs:* does not satisfy it. It is checked when the job is started, not when it is read — the decision is frozen onto the job at that moment, because the worker picks the job up minutes later with no request and no principal behind it. A job started without content cannot be upgraded; start another. Both routes share the drain rate-limit buckets: log-drains-mutate on the start, log-drains-read on the poll.

POST /admin/orgs/:orgId/logs/export

Starts an export. Returns immediately; the work happens on the platform.

string

required

Inclusive lower bound: an ISO 8601 instant, or a relative form such as 15m, 2h, or 7d. A relative form is resolved by the server’s clock.

string

required

Inclusive upper bound; the same formats. The literal string now is not one of them — the vocabulary is an ISO 8601 instant or a relative form, and nothing else. Both bounds are required, so “up to the present moment” is written as an instant you compute yourself.

string[]

Which sources to export. Defaults to every exportable source.

string[]

Up to 200 agent ids. Defaults to every agent in the organization.

string[]

Any of production, sandbox. Defaults to both.

boolean

default:"false"

Include user_message and agent_response bodies. Requires logs:manage.

Response 202 with { "jobId": "lex_…", "state": "queued", "createdAt": "…" }. Poll the status route. Errors

Status	Code	When
`400`	`DRAIN_VALIDATION_FAILED`	The body is malformed; `field` names the offender
`403`	`EXPORT_CONTENT_FORBIDDEN`	`includeContent: true` without `logs:manage`
`409`	`EXPORT_ALREADY_RUNNING`	The organization already has one queued or running
`422`	`EXPORT_WINDOW_INVALID`	A bound will not parse — `now` is the common one, and it is not accepted — or `from` is later than `to`
`422`	`EXPORT_WINDOW_TOO_LARGE`	The range is longer than 31 days
`422`	`EXPORT_SOURCE_UNSUPPORTED`	A source an export cannot produce — see below

Only the eighteen execution-log sources and execution are exportable. The six adjacent-record sources — delivery, trigger-execution, job-execution, workflow-run, voice-call, and workflow-audit — are built for a drain out of the platform’s own ledgers and are not execution-log rows, so there is nothing for an export to read. Naming one answers 422 EXPORT_SOURCE_UNSUPPORTED. To capture them, point a drain at a destination you can read.

lua logs export --since 7d --out ./export

const response = await fetch('https://api.heylua.ai/admin/orgs/<<YOUR_ORG_ID>>/logs/export', {
  method: 'POST',
  headers: { Authorization: 'Bearer <<YOUR_API_KEY>>', 'Content-Type': 'application/json' },
  body: JSON.stringify({ from: '7d', to: new Date().toISOString(), sources: ['skill', 'job', 'execution'] }),
});
const { jobId } = await response.json();

curl -sS -X POST "https://api.heylua.ai/admin/orgs/<<YOUR_ORG_ID>>/logs/export" \
  -H "Authorization: Bearer <<YOUR_API_KEY>>" \
  -H "Content-Type: application/json" \
  -d '{ "from": "2026-09-01T00:00:00Z", "to": "2026-09-22T00:00:00Z", "sources": ["skill"] }'

GET /admin/orgs/:orgId/logs/export/:jobId

Reads one job. A job id belonging to another organization answers 404, never 403 — the two cases are deliberately indistinguishable. Response

{
  "id": "lex_7c1e0b44f9a2d538",
  "orgId": "<<YOUR_ORG_ID>>",
  "state": "succeeded",
  "window": { "from": "2026-09-15T00:00:00.000Z", "to": "2026-09-22T00:00:00.000Z" },
  "selectors": { "sources": ["skill", "job", "execution"], "environments": ["production"], "includeContent": false },
  "counts": { "scanned": 4182230, "rows": 4180117, "scrubHits": 92, "orgScrubHits": 14, "files": 3, "bytes": 190418221 },
  "files": [
    {
      "seq": 1,
      "name": "org-acme-logs-0001.ndjson.gz",
      "rows": 1600000,
      "bytes": 67108864,
      "fileId": "fil_9a1c…",
      "url": "https://cdn.heylua.ai/…?X-Amz-Expires=86400&…"
    }
  ],
  "createdAt": "2026-09-22T09:00:11.004Z",
  "startedAt": "2026-09-22T09:00:16.221Z",
  "finishedAt": "2026-09-22T09:07:44.918Z",
  "expiresAt": "2026-09-23T09:07:44.918Z",
  "deleteAfter": "2026-09-29T09:00:11.004Z"
}

Field	Meaning
`state`	`queued`, `running`, `succeeded`, `failed`, or `expired`
`counts.scanned`	Rows read. On a job that was resumed after an interruption this slightly over-counts
`counts.rows`	Records actually written. Exact, and the number the files hold
`counts.scrubHits`	How many values the scrubber masked, built-in classes and organization rules together
`counts.orgScrubHits`	How many of `scrubHits` came from your organization’s own rules. Optional — absent, rather than `0`, when no organization rule ran
`counts.scrubBudgetExceeded`	Records whose organization-rule pass hit its per-record time budget and so did not run every rule. Optional, and only ever present once organization rules are in play; the built-in classes are never cut short by the budget. Non-zero means re-run with fewer or cheaper rules, not the export failed
`truncated`	Present and `true` when the job hit the row cap. A success with a flag, not a failure
`files[].url`	A signed link, present only while the job is `succeeded` and inside `expiresAt`
`expiresAt`	When the signed links stop working — 24 hours after the job finished. The files are still there; it is the link that has expired
`deleteAfter`	When the job’s links are taken away for good — 7 days after the job was started, not after it finished. The job then reads `expired`; the parts stay listed, so you can still see what the export produced, but no URL is handed out again. It is not when the bytes go: the stored objects are deleted separately, on their own clock
`error`	On `failed`, a short scrubbed reason

Errors

Status	Code	When
`404`	`EXPORT_NOT_FOUND`	No job with that id in this organization

Caps

Cap	Value
Window	31 days
Rows per job	10,000,000 — beyond it the job succeeds with `truncated: true`
Agents named per job	200
Concurrent exports per organization	1
Signed link lifetime	24 hours after the job finishes
Link lifetime (`deleteAfter`)	7 days after the job is started
Stored object lifetime	Between 7 and 8 days after the part was written
Compressed bytes per part	up to 256 MB; parts are cut well below it

Three clocks, and they measure different things.

The signed link — 24 hours after the job finishes (expiresAt). After it, files[].url is gone from the status payload and a link you kept answers 403. There is no supported way to re-issue one — start another export for the same window instead.
The job’s links — 7 days after the job was started (deleteAfter). The job moves to expired and loses its URLs permanently. This is the clock that ends the capability, and it is anchored on the start, not the finish.
The stored objects — between 7 and 8 days after each part was written. The parts live under the log-exports/ key prefix in Lua’s object storage and are removed by that bucket’s own storage lifecycle rule, which sweeps at UTC midnight rather than to the second. Quote “7 to 8 days” when someone asks how long Lua holds the bytes of an export.

The last two run independently and neither waits on the other: deleteAfter withdraws the links, the lifecycle rule removes the bytes. Download inside the 24 hours, or pass --out and keep the bytes. One export runs per organization at a time. That is a guarantee, not a race — a second start answers 409 EXPORT_ALREADY_RUNNING. lua logs export turns that into an attach: a second invocation in a terminal follows the running job to its files rather than refusing. A truncated export is a success. The files are valid and complete as far as they go; they simply do not cover the whole window. Narrow the window or the sources and run it again.

What the files contain

One complete batch per line. Not one record per line. A record has no resource of its own — service.name, lua.org.id, deployment.environment.name, and the agent version all live on the batch’s resource half. A file of bare records would validate against nothing you were given and would drop the tenancy every record depends on. Parts are named org-<orgId>-logs-<NNNN>.ndjson.gz, zero-padded so lexical order is emission order. Each is stored under the log-exports/ key prefix, so a part’s object key is log-exports/<fileId>.gzip and the signed link in files[].url points at exactly that key — which is also what makes the parts expirable on their own storage lifecycle rule, separately from everything else in the bucket:

cat org-acme-logs-*.ndjson.gz | gunzip > window.ndjson

# every record id in a part
gunzip -c org-acme-logs-0001.ndjson.gz | jq -r '.records[].id'

Validate it against the published schema

Each line is one batch and validates against the same JSON Schema a drain delivery does — byte-identical shape, same encoder.

npm i -g ajv-cli
curl -sS https://docs.heylua.ai/schemas/logs/1.0 -o lua-log-batch.schema.json

gunzip -c org-acme-logs-0001.ndjson.gz \
  | while IFS= read -r line; do
      printf '%s' "$line" > /tmp/batch.json
      ajv validate -s lua-log-batch.schema.json -d /tmp/batch.json --errors=text || exit 1
    done && echo "all lines valid"

Build your ingest so an unknown attributes key is carried through rather than rejected — additions are additive within a major version, and a schema addition should never fail a load.

What is not in them

Rows written before organization attribution existed. A row that never recorded an organization cannot be attributed to one, so it is in no org-scoped export. These are the oldest rows only, and the boundary is fixed: nothing written since carries the gap.
log-type rows with no source. A row the platform never classified is counted in counts.scanned and not in counts.rows.
Message bodies, unless the job was started with logs:manage and includeContent: true. The record still arrives, carrying lua.content.withheld: true.
Anything the scrubber caught. Scrubbing is unconditional: there is no flag that skips it, and includeContent: true does not weaken it. An export runs the built-in rule classes (builtin, lua-token, vendor-key) and, where the deployment has it enabled, the union of your organization’s active drains’ own rules as well — see the note at the top of this page.

Retention bounds what you can export

The platform keeps execution logs for 90 days by default. An export can only read what is still there, so a window whose lower bound is older than the retention horizon returns the part of it that survives, not an error. Export before you need to, not after.

The CSV download is deprecated

GET /admin/orgs/:orgId/logs/download still works and still caps at 10,000 rows. It is deprecated in favour of this job:

	CSV download	Export job
Rows	10,000, silently truncated	10,000,000, and it says when it truncated
Shape	A flat 9-column CSV	The published event schema, byte-identical to a drain delivery
Window	Any, but you still only get 10,000 rows	≤ 31 days, complete
Delivery	One synchronous response	An asynchronous job with signed links
Scrubbing	None	The full built-in rule set, unconditional, plus your organization’s own rules where the deployment has them enabled

Nothing about the CSV route has changed. Its removal will be its own change, with its own release note.

SDK

CLI

REST API

Scopes

POST /admin/orgs/:orgId/logs/export

GET /admin/orgs/:orgId/logs/export/:jobId

Caps

What the files contain

Validate it against the published schema

What is not in them

Retention bounds what you can export

The CSV download is deprecated

See also

​Scopes

​POST /admin/orgs/:orgId/logs/export

​GET /admin/orgs/:orgId/logs/export/:jobId

​Caps

​What the files contain

​Validate it against the published schema

​What is not in them

​Retention bounds what you can export

​The CSV download is deprecated

​See also

Scopes

POST /admin/orgs/:orgId/logs/export

GET /admin/orgs/:orgId/logs/export/:jobId

Caps

What the files contain

Validate it against the published schema

What is not in them

Retention bounds what you can export

The CSV download is deprecated

See also