Clusters

Failure clusters in Qualflare group similar test failures together, helping you identify patterns and common root causes. The clusters commands let you list and inspect cluster records across your project.

qf clusters list

List all failure clusters in the project, with optional filters for severity.

Syntax

qf clusters list [flags]

Flags

Flag	Type	Default	Description
--severity	string slice	—	Filter by severity. Accepts comma-separated values: critical, high, medium, low
--page	int	0	Page number for paginated results
--sort-by	string	—	Field name to sort results by
--sort-desc	bool	false	Sort results in descending order
--api-key	string	—	API key for authentication. Overrides QF_API_KEY environment variable

Examples

# List all failure clusters
qf clusters list

# Filter by a single severity
qf clusters list --severity critical

# Filter by multiple severities
qf clusters list --severity critical,high

# Sort by failure count, highest first
qf clusters list --sort-by failureCount --sort-desc

# Paginate through results
qf clusters list --page 2

Example Output

{
  "clusters": [
    {
      "id": 15,
      "severity": "critical",
      "failureCount": 38,
      "pattern": "NullPointerException in PaymentService.processRefund",
      "firstSeenAt": "2026-03-15T09:10:00Z",
      "lastSeenAt": "2026-03-28T17:45:00Z"
    }
  ],
  "total": 1
}

---

qf cluster get <id>

Fetch full details for a single failure cluster by its ID.

Note: Unlike most other resources (which use <seq>), cluster lookup uses an <id>. Make sure to pass the cluster's ID, not its sequence number.

Syntax

qf cluster get <id>

Arguments

Argument	Description
id	The ID of the failure cluster to retrieve

Flags

Flag	Type	Default	Description
--api-key	string	—	API key for authentication. Overrides QF_API_KEY environment variable

Examples

# Get failure cluster with ID 15
qf cluster get 15

# Get cluster and pipe to jq
qf cluster get 15 | jq '.pattern'

Example Output

{
  "id": 15,
  "severity": "critical",
  "failureCount": 38,
  "pattern": "NullPointerException in PaymentService.processRefund",
  "firstSeenAt": "2026-03-15T09:10:00Z",
  "lastSeenAt": "2026-03-28T17:45:00Z"
}

Working with JSON Output

All cluster commands output pretty-printed JSON to stdout, making them easy to pipe to jq for filtering and transformation.

# List all cluster patterns
qf clusters list | jq '.clusters[].pattern'

# Find the cluster with the highest failure count
qf clusters list | jq '.clusters | max_by(.failureCount) | {id, pattern, failureCount}'

# Count clusters by severity
qf clusters list | jq '[.clusters[].severity] | group_by(.) | map({severity: .[0], count: length})'

# Get all critical cluster IDs
qf clusters list --severity critical | jq '[.clusters[].id]'

# Check the failure count for a specific cluster
qf cluster get 15 | jq '.failureCount'

See Also

• Defects — List and inspect defect records linked to failed test cases
• Other Commands — Utility commands including validate and list-formats
• Configuration — Environment variables and global flags reference