Analysis execution and run investigation

Role: Model user; model administrators may also inspect their model’s runs. Prerequisites: An accessible publication and its execution/data-access disclosure. Files: A private analysis directory and model-specific inputs; accepted run IDs are useful for investigation and recovery.

Start one analysis

For first use, follow your first run. The complete analysis guide owns initialization, reviewed submission, file/collection bindings, retries and verified collection. Use a new directory for each intended execution; repeat commands in the original directory after interruption.

An acceptance receipt records original acceptance, including its initial queued state. Use status or waiting for current progress. For saved operations from the former CLI, use import or attachment with the original identity. The sections below explain retained run history and investigation by ID, independently of the local folder.

Inspect progress and results

For an analysis directory, use analysis status, analysis logs, analysis wait and analysis cancel directly. For authorized investigation of accepted work by ID, use the retained commands below. Replace RUN_UUID with an ID from authorized history or retained evidence:

enumeray run list
enumeray run get RUN_UUID
enumeray --json run wait RUN_UUID --interval 2 --deadline 3600 > final-run.json
enumeray run events RUN_UUID

run list returns your run history. run get includes current state and the applicable progress or queue diagnostics. Public states are queued, running, succeeded, failed and cancelled. While running, the phase distinguishes preparation, backend waiting, execution, collection and uploading. Inspect freshness and backend evidence before drawing conclusions about stale progress. Human observation names the next responsible role for known problems and leaves unclassified waiting unexplained. Wait updates include phase, blockage, freshness, execution-control and cancellation changes; timestamp refreshes alone do not repeat progress.

run wait polls until a terminal state or its local deadline. The deadline does not impose a scientific runtime limit and does not cancel work. By default its exit status is 0 for any successfully observed terminal state, including failure and cancellation. Add --check-outcome to return 0 for success, 3 for failure, 4 for cancellation and 5 for local deadline expiry. Terminal JSON remains on stdout for exit 3/4; a deadline produces no terminal response. Ordinary errors exit 1, invalid arguments 2 and interruption 130. Without --check-outcome, deadline expiry still exits 1. See the lifecycle reference for queue-block reasons and cancellation status.

Read these inspection fields together:

Field	How to use it
state	Decide whether to keep waiting or inspect a final outcome.
phase	While running, distinguish preparing, waiting_for_backend, executing, collecting_results and uploading_results.
observation_freshness, last_observed_at	Decide whether the last confirmed observation is recent; stale does not mean failed.
blocked_reason	Identify an eligibility problem on queued work for the responsible owner.
execution_control	See current execution authorization, pending revocation or draining.
cancellation	See durable user cancellation intent and confirmation.
result.outputs, result.files, result.failure	Read scientific values, file references or the final failure. result can be null before final delivery.

JSON outputs are returned in run inspection. File outputs are artifact references. Required output validation and verified publication precede public success; a completed backend job may still be collecting or uploading results.

Script with structured output

Use the global --json option for compact machine-readable output. Runtime error objects are JSON on stderr; progress and recovery hints also use stderr. Argument parsing errors use plain-text stderr and exit 2, including with --json. Check the command’s exit status and parse the returned structure, rather than grepping presentation text. --timeout bounds an individual HTTP operation; it is separate from analysis wait --deadline and the model’s runtime.

The complete noninteractive analysis recipe separates initialization and destination/disclosure review from the resumable submit/wait/collect stage. It requires jq, saves structured summaries, preserves scientific failure/cancellation exits and checks full collection completeness without extracting UUIDs. Use the same directory after interruption or credential renewal.

Native CLI output uses human tables, labelled details and receipts by default, including when stdout is redirected. Use --json for saved or parsed evidence; its response fields remain unchanged. The raw api escape hatch retains pretty JSON unless --json is supplied. API failures include an HTTP status and an error with code, message and request_id; local failures use error.code: client_error.

run list fetches the first history page (20 runs by default). For filters or additional pages, use the native command:

enumeray run list --model example --status succeeded --limit 20
# Follow the printed Next page command for interactive navigation.
# Scripts retain the response and pass the opaque cursor unchanged:
enumeray --json run list --model example --status succeeded --limit 100 > history.json
CURSOR=$(jq -r '.next_cursor // empty' history.json)
if [ -n "$CURSOR" ]; then
  enumeray --json run list --model example --status succeeded --limit 100 --cursor "$CURSOR"
fi

Use --created-after and --created-before for exclusive RFC3339 creation-time bounds. Page sizes range from 1 through 100; omission retains the API default of 20 for personal run history. Each command fetches only one page. Keep the same filters when following the cursor; do not construct or decode it. Administrator model runs and connector runs inventories accept pagination but do not support these personal-history filters. General API examples are in HTTP workflows.

Model-administrator inspection

enumeray model runs example
enumeray model audit example

Current model owners and co-admins can inspect their model’s runs, including scientific inputs, logs, results, provenance and referenced artifacts. These reads are audited. Submitters retain historical run access after a model-access revocation. Connector-only administration does not grant scientific-data inspection.

Expected outcome: One analysis with retained acceptance and interpretable result evidence, or an authorized investigation of existing work. Next: Read logs and export provenance, or cancel or retry when needed.