---
title: "Get failure clusters"
method: GET
path: "/api/v1/user/projects/{projectId}/test-runs/{testRunId}/failure-clusters"
tags: ["Test History"]
---

# Get failure clusters

`GET /api/v1/user/projects/{projectId}/test-runs/{testRunId}/failure-clusters`

## Request

- Base URL: `https://app.gaffer.sh`
- URL: `https://app.gaffer.sh/api/v1/user/projects/{projectId}/test-runs/{testRunId}/failure-clusters`
- Auth: one of:
  - API key in header `X-API-Key`
  - API key in header `X-API-Key`
  - HTTP bearer

Groups failed tests by error message similarity using Levenshtein distance.
Helps identify root causes when multiple tests fail. Often 15 failures are 2-3 bugs.

## Path parameters

- `projectId` string, required
- `testRunId` string, required

## Response `200`

Failure clusters grouped by error similarity

- FailureClustersResponse: Failed tests grouped by error message similarity.
  - `clusters` FailureCluster[], required
    - `representativeError` string, required: The error message representing this cluster
    - `count` integer, required: Number of tests in this cluster
    - `tests` FailedTest[], required
      - `name` string, required: Short test name
      - `fullName` string, required: Full test name including describe blocks
      - `errorMessage` string, required: The error message for this test
      - `filePath` string, nullable: Test file path
    - `similarity` number, required: Similarity threshold used for clustering (0-1)
    - `aiCategory` FailureCategory, nullable: AI-generated categorization of a failure cluster's root cause.
      - `category` 'product_bug' | 'automation_bug' | 'environment_issue', required: The classified root cause category
      - `confidence` 'high' | 'medium', required: Confidence level of the classification
      - `reasoning` string, required: Brief explanation of why this category was chosen
  - `totalFailures` integer, required: Total number of failed tests across all clusters

## Other responses

- `400`: Invalid request parameters
- `401`: Missing or invalid API key
- `404`: Resource not found

---

[API](https://skmtc.dev/gaffer/apis/gaffer-api.md) · [All operations](https://skmtc.dev/gaffer/apis/gaffer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gaffer/apis/gaffer-api/revisions/d742ab303118?raw)