export-trace

Export Trace

Retrieve one explicit hosted trace without scanning the capture catalog. Resolve its request IDs through the customer trace lookup endpoint, then reuse the bounded request capture exporter.

Safety Gates

• Treat a bare trace_id as authorization for a redacted local summary export, not for raw prompts or completions.
• Use --include-payload --yes only when the developer explicitly asks for the full, raw, or complete trace/captures. Announce that the files may contain prompts, completions, and tool payloads before running it.
• Keep outputs under .understudy/; never print, paste, commit, or upload trace bodies.
• Never ask for API keys in chat. Use existing Understudy credentials and report only auth presence or errors.
• Never replace the trace lookup with project-wide capture pagination. If the lookup endpoint is unavailable, stop and report the backend dependency.

Resolve CLI

Prefer the installed understudy binary. In this repository checkout:

npm run build
node dist/bin.js status --json

Use node dist/bin.js in place of understudy below when necessary.

Flow

1. Resolve the project from repo config or an explicit --project / --project-id. Resolve --workload only when the developer supplied or requested that narrower scope.

2. For redacted metadata, run:

   understudy traces export <trace-id> \
     --project <project> \
     --out .understudy/traces/<trace-id>
   

3. For an explicitly requested full trace, run:

   understudy traces export <trace-id> \
     --project <project> \
     --out .understudy/traces/<trace-id> \
     --include-payload --yes
   

   For several explicit IDs, put one per line in a private local file and use --trace-ids-file <path>. Do not use or recreate an unbounded --all operation.

4. Inspect only metadata artifacts:

   • trace.json — trace_id, ordered request_ids, and export counts;
   • failed-request-ids.txt — request captures to retry;
   • failed-trace-ids.txt — trace lookups or trace exports to retry;
   • *.summary.json or *.payload.json — private per-request files.