# Failure clusters API Source: https://docs.qualflare.com/docs/api/failure-clusters ยท Last updated: 2026-11-03 List and read the failure clusters Qualflare groups from your uploaded results over the REST API, with severity and status filters and sample failures. 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. | | | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | **Base path** | `/api/v1/clusters` and `/api/v1/cluster/{clusterId}`. A cluster is addressed by its `id`, not a `seq` | | **Reads** | Any token. Token creator: (requires the Viewer role or higher in the project). The API has no cluster writes | | **Pages** | `limit` 1 to 100 clusters per page, 10 by default, as `items` and `paging` | | **Limits** | [Rate limits and request sizes](https://docs.qualflare.com/docs/api/limits) | | **Errors** | [Errors and status codes](https://docs.qualflare.com/docs/api/errors) | | **CLI** | `qf clusters list`, `qf cluster get ` ([Clusters commands](https://docs.qualflare.com/docs/cli/read-commands#clusters)) | | **MCP** | `list_failure_clusters`, `get_failure_cluster` ([MCP server reference](https://docs.qualflare.com/docs/api/mcp-reference)) | | **Plans** | Which plans create clusters: [Failure Clusters](https://docs.qualflare.com/docs/ai/failure-clusters#accessing-clusters) | The two endpoints, each with its own section below: | Endpoint | What it does | | ------------------------------------- | ------------------------------------------------------------------------------------------------ | | **GET** `/api/v1/clusters` | [List failure clusters](https://docs.qualflare.com/docs/api/failure-clusters#list-clusters) | | **GET** `/api/v1/cluster/{clusterId}` | [Get a failure cluster](https://docs.qualflare.com/docs/api/failure-clusters#get-cluster) | ## 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. | Name | Type | Default | Required | Description | | ------------ | ---------------- | -------------- | -------- | ------------------------------------------------------------------- | | `limit` | `query`, integer | `10` | No | Clusters per page, 1 to 100 | | `page` | `query`, integer | `1` | No | Page number, 1 to 1,000 | | `severity[]` | `query`, string | | No | `low`, `medium`, `high` or `critical`. Repeat it for more, up to 10 | | `status[]` | `query`, string | | No | `pending` or `analysed`. Repeat it for both | | `q` | `query`, string | | No | Text to look for in cluster labels, up to 255 characters | | `sortBy` | `query`, string | `failureCount` | No | `failureCount`, `firstSeenAt`, `lastSeenAt`, `severity` or `label` | | `sortDir` | `query`, boolean | `true` | No | `false` sorts in ascending order | ```bash 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. | Name | Type | Default | Required | Description | | ----------- | --------------- | ------- | -------- | ---------------- | | `clusterId` | `path`, integer | | Yes | The cluster `id` | ```bash 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`. ```json { "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: | Field | Type | Notes | | ---------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- | | `id` | integer | The cluster `id`, which [Get a failure cluster](https://docs.qualflare.com/docs/api/failure-clusters#get-cluster) takes | | `label` | string | The cluster's name | | `summary` | string | A short description of the cluster | | `failureCount` | integer | The failures in the cluster | | `severity` | string | `low`, `medium`, `high` or `critical` | | `status` | string | `pending` until the AI analysis has run, then `analysed` | | `firstSeenAt`, `lastSeenAt` | string | When its first and its latest failure were seen | | `rootCause`, `fixSuggestion` | string | The analysis's root cause and suggested fix, or `null` | | `createdAt`, `updatedAt` | string | RFC 3339 timestamps | | `sampleFailures` | array | On get only: up to 10 failures, with the fields below. Left out of list items | ### Sample failure fields Each item of `sampleFailures` is one failed case result: | Field | Type | Notes | | --------------------------- | ------- | ----------------------------------------------------------------- | | `caseRunId` | integer | The case result's ID | | `caseName`, `suiteName` | string | The test case and its suite | | `errorText` | string | The error the test reported | | `similarity` | number | How close the failure is to the cluster | | `launchSeq` | integer | The [launch](https://docs.qualflare.com/docs/api/launches) number | | `caseRunSeq`, `suiteRunSeq` | integer | The numbers of the case result and of its suite run | ## CLI and MCP equivalents The qf CLI and the MCP server run the same reads, so they return the same JSON: | REST | qf command and MCP tool | | ------------------------------------- | --------------------------------------------------------- | | **GET** `/api/v1/clusters` | `qf clusters list`; `list_failure_clusters` | | **GET** `/api/v1/cluster/{clusterId}` | `qf cluster get `; `get_failure_cluster` | ## Related * **Guides:** [Failure Clusters](https://docs.qualflare.com/docs/ai/failure-clusters) * **Reference:** [Defects API](https://docs.qualflare.com/docs/api/defects) * **CLI/API:** [Qualflare API](https://docs.qualflare.com/docs/api)