kt export-jobs

Use kt export-jobs to create and download date-bounded decision-event artifacts without keeping a terminal attached while the export worker runs. The jobs are scoped to the authenticated organization and selected API region.

This command group exports Events. It does not export immutable Trail change records or History content.

Prerequisites

• Authenticate with KEEPTRUSTS_API_TOKEN or kt auth login.
• Select the profile and region that contain the evidence.
• Use a role or token with exports:read to list, inspect, and download jobs.
• Add exports:write to create jobs.
• Confirm that the relevant application traffic produced Events in the control plane.

All subcommands accept the standard connection overrides: --config <path>, --api-url <url>, --api-token <token>, --profile <name>, and --region <region>.

Command summary

Command	Purpose
kt export-jobs list [--json]	List the organization's export jobs and lifecycle states.
kt export-jobs get --job-id <id> [--json]	Read one job's current lifecycle record.
kt export-jobs create ...	Queue a new asynchronous Events export.
kt export-jobs download --job-id <id>	Stream a completed artifact to stdout.

Supported formats

The asynchronous API and this command use the same format set:

Value	Output	Purpose
csv	CSV decision-event rows	Spreadsheet review and data exchange
json	Structured JSON decision-event data	Programmatic processing
compliance-aesia	JSON report	AESIA-aligned evidence review
compliance-aepd	JSON report	AEPD-aligned evidence review
compliance-ens	JSON report	ENS-aligned evidence review
compliance-all	.tar.gz bundle	Manifest plus the organization's selected framework reports; all three reports are included when no valid framework selection is stored

Compliance reports are evidence summaries, not compliance certifications.

The direct kt events export workflow implements only csv and json; it is separate from these asynchronous formats. Use kt trail export when you need filtered immutable Trail records.

List jobs

kt export-jobs list

Plain output prints one row per job:

<job-id>  <status>  <format>  <requested-at>

Use --json to retain the full API response, including job metadata and the queue topic. Completed job objects can also include integrity, with the recorded artifact SHA-256, manifest SHA-256, byte size, event count, append-only indicator, and recording time:

kt export-jobs list --json

Inspect one job

JOB_ID="exp_replace_with_created_id"
kt export-jobs get --job-id "$JOB_ID"

Plain output includes the job ID, state, format, request time, inclusive date window, exported row count when available, and failure message when present. --json prints the matching job object.

The command reads from the organization-scoped job list. A job created under a different organization, profile, or region is reported as not found.

Create a job

Create a job with either a relative window or two explicit dates.

Relative window

kt export-jobs create --since 30d --format csv

--since accepts a positive integer followed by h or d, such as 24h, 7d, or 30d. Zero and negative durations fail locally. The CLI subtracts that duration from the current UTC time and sends the resulting start and end calendar dates. The API exports both dates in full, so this is a day-granular window rather than an exact rolling-hour query.

Use explicit dates when a reviewer supplied exact calendar boundaries.

Explicit dates

START_DATE="YYYY-MM-DD"
END_DATE="YYYY-MM-DD"

kt export-jobs create \
  --start-date "$START_DATE" \
  --end-date "$END_DATE" \
  --format json

Both dates are required and inclusive. When both are present, they take precedence over --since. Supplying only one explicit date is an error even when --since is also present. Both values must use YYYY-MM-DD, and the start date must be on or before the end date.

Wait for a terminal state

kt export-jobs create \
  --since 7d \
  --format csv \
  --wait \
  --wait-timeout-secs 180

With --wait, the CLI polls the job list every two seconds until the created job reaches:

• completed: exits successfully;
• failed: exits with the job's failure message when available; or
• expired: exits with an error because no downloadable artifact remains.

The default timeout is 120 seconds. A timeout stops local polling; it does not cancel the server-side job. Use list or get to continue tracking it.

Without --wait, --json prints the create response with job and queue_topic. With --wait, --json prints the completed job object.

Create options

Flag	Description
--since <duration>	Relative duration expressed with h or d.
--start-date <YYYY-MM-DD>	Inclusive start date; use with --end-date.
--end-date <YYYY-MM-DD>	Inclusive end date; use with --start-date.
--format <format>	One of the six values in Supported formats.
--wait	Poll until the job completes, fails, expires, or times out.
--wait-timeout-secs <n>	Maximum polling time when --wait is set; default 120.
--json	Print structured output.

Understand lifecycle states

State	Meaning	Next action
queued	The API accepted the job and it is waiting for a worker.	Wait or inspect later.
processing	A worker claimed the job and is building the artifact.	Wait; do not create a duplicate.
completed	Processing finished.	Confirm download_ready, then download.
failed	Processing stopped.	Read failure_message, correct the cause, and create a new job.
expired	The stored artifact is no longer available.	Create a replacement from the recorded window and format.

Download an artifact

Choose an extension that matches the job format:

JOB_ID="exp_replace_with_completed_id"
kt export-jobs download --job-id "$JOB_ID" > export-evidence.csv

The command writes only artifact bytes to stdout, which makes shell redirection safe. Download succeeds only for a completed job with a ready artifact.

After download:

1. Compare the file with the job's dates, format, row count, and filename.
2. Inspect a representative sample or the bundle manifest.
3. Calculate SHA-256 with approved evidence tooling and compare it with integrity.artifact_sha256 from list --json or get --json.
4. Retrieve /v1/exports/jobs/{job_id}/manifest when you need the persisted manifest, artifact inventory, and integrity record.
5. Store and share the artifact through the approved evidence process.

The API may answer the download route with a temporary redirect when S3-compatible storage is configured. kt export-jobs download follows that redirect before writing bytes to stdout.

Inspect the persisted manifest

There is no separate manifest subcommand. Use the authenticated API route:

curl --fail --silent --show-error \
  --header "Authorization: Bearer $KEEPTRUSTS_API_TOKEN" \
  "$KEEPTRUSTS_API_URL/v1/exports/jobs/$JOB_ID/manifest"

The response includes manifest, artifact_inventory, and integrity. Compare the downloaded bytes with integrity.artifact_sha256; do not compare them with manifest_sha256, which covers the manifest record instead.

End-to-end example

# Queue the export and copy the returned job ID.
kt export-jobs create --since 30d --format csv

JOB_ID="exp_replace_with_created_id"

# Read the lifecycle record until status is completed.
kt export-jobs get --job-id "$JOB_ID"

# Save the completed artifact.
kt export-jobs download --job-id "$JOB_ID" > export-evidence.csv

For automation, prefer structured output:

kt export-jobs create \
  --since 30d \
  --format json \
  --wait \
  --wait-timeout-secs 300 \
  --json

Do not assume a successful wait also saved the artifact. create --wait tracks the job; download is a separate command.

Troubleshooting

Authentication or authorization fails

• Confirm the active API URL, profile, organization, and region.
• Confirm the token is current.
• Use exports:read for list, get, and download.
• Use exports:write for create.

The job is not found

Check for an ID transcription error, then confirm that get is using the same organization, profile, and region where the job was created.

Create rejects the window

Supply a positive --since duration or both explicit dates. Partial explicit date pairs fail even if --since is present. Use YYYY-MM-DD, and keep the start date on or before the end date.

Wait times out

The job continues server-side. Run kt export-jobs get --job-id <id> rather than creating a duplicate. If the job remains queued or processing longer than your operating threshold, preserve the ID and escalate the worker issue.

The job failed

Run get --json and preserve failure_message with the job ID. Correct the reported cause and request a new job. Failed jobs cannot be downloaded.

Download returns not ready or expired

Check the job state and download_ready. Wait for completed; if the job is expired, recreate it from the recorded dates and format.

The artifact is empty or incomplete

Confirm the organization, region, inclusive dates, and that the application produced Events in the control plane. Then confirm that you did not need Trail, History, or Inbox evidence instead. Widen the window only when the review scope allows it.

Next steps

• Export evidence for a review
• kt events
• Trail CLI
• Permissions reference