Failure clusters API

The Failure clusters API lets you list and read the failure clusters of a Qualflare project over REST at https://api.qualflare.com/api/v1/clusters, authenticated with a project access token.

The two endpoints, each with its own section below:

List failure clusters

List failure clusters returns one page of the project's failure clusters, most failures first by default.

GET /api/v1/clusters

Needs a project access token whose creator has the Viewer role or higher in the project.

curl -sS -g "https://api.qualflare.com/api/v1/clusters?severity[]=high" \
  -H "Authorization: Bearer $QF_TOKEN"

Returns 200: A page of clusters: items and paging, most failures first by default.

• Filter by severity[], status[] (pending or analysed) and q, a search in the label. The bracketed names can repeat, and the curl example passes -g so curl sends the brackets as they are.

Get a failure cluster

Get a failure cluster returns one cluster by its id and adds up to 10 of the cluster's failures in sampleFailures.

GET /api/v1/cluster/{clusterId}

Needs a project access token whose creator has the Viewer role or higher in the project.

curl -sS "https://api.qualflare.com/api/v1/cluster/15" \
  -H "Authorization: Bearer $QF_TOKEN"

Returns 200: The cluster, with up to 10 of its failures in sampleFailures.

{
  "id": 15,
  "label": "Refund requests time out in the payment service",
  "summary": "Refund tests fail after 30 seconds waiting for the payment service to answer.",
  "failureCount": 38,
  "severity": "critical",
  "status": "analysed",
  "firstSeenAt": "2026-10-19T07:55:10Z",
  "lastSeenAt": "2026-10-28T09:12:33Z",
  "rootCause": "The refund call waits on a lock the nightly settlement job holds.",
  "fixSuggestion": "Run the settlement job outside test hours, or give refunds their own lock.",
  "createdAt": "2026-10-19T08:01:47Z",
  "updatedAt": "2026-10-28T09:20:15Z",
  "sampleFailures": [
    {
      "caseRunId": 90412,
      "caseName": "Refund a paid order",
      "suiteName": "Payments",
      "errorText": "TimeoutError: waiting for /refunds to answer exceeded 30000 ms",
      "similarity": 0.94,
      "launchSeq": 88,
      "caseRunSeq": 1204,
      "suiteRunSeq": 310
    }
  ]
}

• An id that isn't a cluster of the project answers 404 with cluster not found.

Cluster fields

Every cluster the Failure clusters API returns has these fields:

Sample failure fields

Each item of sampleFailures is one failed case result:

CLI and MCP equivalents

The qf CLI and the MCP server run the same reads, so they return the same JSON:

Related

• Guides: Failure Clusters
• Reference: Defects API
• CLI/API: Qualflare API