Skip to main content
POST
Run failure analysis

Authorizations

Authorization
string
header
required

Valiqor API key. Pass as Bearer token: Authorization: Bearer vq-xxxxxxxxxxxxxxxxxxxx

Body

application/json

Request for failure analysis.

trace_id
string | null

Trace ID for full trace analysis

dataset
MinimalInputItem · object[] | null

Dataset items for minimal input analysis

project_name
string | null

Project name for organization

feature_kind
string | null

App type hint: 'rag', 'agent', 'agentic_rag', 'generic_llm'. Auto-detected if not provided.

run_eval
boolean
default:true

Run evaluation metrics alongside failure analysis

run_security
boolean
default:true

Run security audit alongside failure analysis

run_scan
boolean
default:true

Fetch and attach AST scan data if available (auto-enabled for trace inputs)

mandatory_eval_metrics
string[]

User-specified eval metrics that must run

mandatory_security_categories
string[]

User-specified security categories that must run

subcategories
string[] | null

Filter to specific failure subcategories. If None, runs all applicable.

buckets
string[] | null

Filter to specific failure buckets (e.g., 'hallucination_grounding', 'instruction_compliance'). All subcategories within the specified buckets will be included. If both buckets and subcategories are provided, they are merged (union).

openai_api_key
string | null

OpenAI API key for LLM judges

Response

Successful Response

Full failure analysis response.

run_id
string
required
status
string
required

'completed', 'processing', 'failed'

mode
string
required

'minimal' or 'full'

input_type
string
required

'trace', 'json', or 'csv'

feature_kind
string
required

Detected or specified app type

summary
FailureSummary · object
required

Summary of failure analysis results.

failure_tags
FailureTagResponse · object[]
inputs
FARunInputResponse · object[]

Original input items with per-item failure stats

eval_metrics
Eval Metrics · object | null

Evaluation metric scores

eval_run_id
string | null

ID of linked evaluation run

security_flags
Security Flags · object | null

Security category flags

security_batch_id
string | null

ID of linked security audit batch

detectors_run
string[]

Subcategories that were analyzed

detectors_skipped
string[]

Subcategories skipped (not applicable)

duration_ms
integer
default:0
tokens_used
integer
default:0
created_at
string<date-time>