Failure Analysis

All failure analysis commands live under the fa group.

valiqor fa <run|status|result|list>

Common Flags

Every fa subcommand accepts:

Flag	Type	Default	Description
`--api-key`	`string`	—	API key override
`--project`	`string`	—	Project name override
`--base-url`	`string`	—	Backend URL override

fa run

Run failure analysis on a trace or dataset.

valiqor fa run [--trace-id <id> | --dataset <path>] [flags]

Flag	Type	Default	Description
`--trace-id`	`string`	—	Trace UUID to analyze
`--dataset`	`string`	—	Path to a dataset JSON file
`--feature-kind`	`rag \| agent \| agentic_rag \| generic_llm`	auto-detected	Application type hint
`--no-eval`	`flag`	`false`	Skip evaluation metrics
`--no-security`	`flag`	`false`	Skip security audit
`--buckets`	`string`	—	Comma-separated failure bucket filter (e.g. `hallucination,safety`)
`--async`	`flag`	`false`	Submit asynchronously and return a job ID

--trace-id and --dataset are mutually exclusive. At least one is required.

Examples

# Analyze a trace (synchronous)
valiqor fa run --trace-id 550e8400-e29b-41d4-a716-446655440000

# Analyze a dataset, skip security
valiqor fa run --dataset inputs.json --no-security

# Filter specific failure buckets
valiqor fa run --trace-id abc123 --buckets hallucination,safety

# Async analysis
valiqor fa run --dataset inputs.json --async

Output

Displays:

Summary — failures detected, passes, severity, confidence, primary failure
Alert & CI-gate recommendations
Per-failure tags — bucket, subcategory, decision, severity, confidence, detector, rationale
Linked results — associated eval run ID and security batch ID (if applicable)

fa status

Check the status of a failure analysis run.

valiqor fa status --run-id <id> [flags]

Flag	Type	Default	Description
`--run-id`	`string`	required	FA run or job ID
`--wait` / `-w`	`flag`	`false`	Poll until completion with a live progress bar

# Check status once
valiqor fa status --run-id abc123

# Wait with progress bar and ETA
valiqor fa status --run-id abc123 --wait

In wait mode, the CLI polls every 3 seconds until the run completes, fails, or is cancelled.

fa result

Fetch and display failure analysis results.

valiqor fa result --run-id <id> [flags]

Flag	Type	Default	Description
`--run-id`	`string`	required	FA run ID
`--json`	`flag`	`false`	Output raw JSON instead of formatted display

JSON Output Fields

When using --json, the output includes:

Field	Description
`run_id`	Unique run identifier
`status`	Run status
`mode`	Analysis mode
`input_type`	Input source type
`feature_kind`	Detected or specified application type
`summary`	High-level results summary
`failure_tags`	Array of detected failure tags
`eval_run_id`	Linked evaluation run (if applicable)
`security_batch_id`	Linked security batch (if applicable)
`duration_ms`	Processing duration in milliseconds
`tokens_used`	Token consumption for this run

# Formatted output
valiqor fa result --run-id abc123

# Raw JSON for scripting or CI/CD
valiqor fa result --run-id abc123 --json

fa list

List failure analysis runs with pagination.

valiqor fa list [flags]

Flag	Type	Default	Description
`--status`	`completed \| failed \| running \| cancelled`	—	Filter by run status
`--page`	`int`	`1`	Page number
`--page-size`	`int`	`15`	Items per page

Examples

# List all runs
valiqor fa list

# List only completed runs
valiqor fa list --status completed

# Paginate through results
valiqor fa list --page 2 --page-size 10

Displays run ID, status, input type, failure count, primary failure, and created date.

Getting Started

Commands

Failure Analysis

Common Flags

fa run

Examples

Output

fa status

fa result

JSON Output Fields

fa list

Examples

​Common Flags

​fa run

​Examples

​Output

​fa status

​fa result

​JSON Output Fields

​fa list

​Examples

Common Flags

fa run

Examples

Output

fa status

fa result

JSON Output Fields

fa list

Examples