In ReportPortal, a launch's generated error clusters are returned as `ClusterInfoResource` objects. What do the `index`, `message`, `matchedTests` and `launchId` fields on one of them tell you?

## What clustering produces ReportPortal's unique-error clustering takes the failing test items of **one launch** and groups them by how similar their failure text is, with nobody having written a rule first. Each group that comes out is one row in the clusters table, and the API renders that row as a `ClusterInfoResource`. Two calls bracket the feature. One **starts** generation for a launch and returns an acknowledgement that generation has started -- the work runs asynchronously in the analyzer service. A second call **reads back** the clusters that now exist for that launch. An empty list a second after the first call means "not finished yet", not "no clusters found". Generation is also refused outright for a launch that is still `IN_PROGRESS`, so the sequence is: finish the launch, start generation, then read. ## The fields, one at a time | field | what it holds | |---|---| | `id` | the cluster row's own database key | | `index` | the identifier the analyzer gave this group; the stored entity holds the same value as `indexId` | | `launchId` | the launch this cluster belongs to | | `message` | the representative failure text the group formed around | | `matchedTests` | how many test items fell into the group | | `metadata` | a free-form map carried alongside the cluster | - **`message` is the entire basis of the grouping.** Clustering here is a text operation over failure messages. Everything a cluster claims is a claim about strings, which is why a message that embeds a request id or a timestamp behaves so differently from one that does not. - **`matchedTests` is a count, not a list.** It is computed as the number of test items linked to that cluster. To see *which* items, you follow the cluster; to judge whether the grouping is any good, the count alone is usually enough. - **`index` and `id` are two different numbers.** `id` is the row's primary key inside ReportPortal. `index` is the identifier the analyzer assigned the group, and the persisted entity calls that field `indexId` -- the API just renames it on the way out. Quoting one where the other was meant is the classic confusion when someone scripts against this endpoint. - **`launchId` is the scope, and it is the field people skip over.** A cluster is a per-launch object. The entity also carries a `projectId`, but that is addressing, not scope: the row still names exactly one launch. ## Reading a cluster list Because `matchedTests` sits on every row, the *shape* of the list is diagnostic before you open a single cluster: 1. One cluster whose `matchedTests` is close to the launch's entire failure count, sitting under a short, generic `message` -- the grouping merged problems that are not the same problem. 2. A long list in which nearly every `matchedTests` is 1 -- the grouping split one problem into many, usually because the messages carry text that varies run to run. 3. A handful of clusters with plausible counts and messages you can read as distinct failures -- the shape you actually want. That reading is the everyday use of the endpoint. You are not looking for a number; you are looking at a distribution. ## What a cluster is not A cluster is a **proposal about text**, not a verdict about defects. Nothing in `ClusterInfoResource` says "these are the same bug", assigns a defect type, or links a ticket. Those are separate acts performed by people and by other parts of the product, on top of a grouping that clustering merely offered. Treating a cluster as a defect record is the single most common overreach, and it shows up as soon as two genuinely different failures land in one cluster because they share a wrapper message. Equally, a cluster is not a rule. Nobody wrote a pattern that produced it, so nobody can point at the pattern to explain why two failures are together -- the only explanation available is the `message` the cluster formed around, plus whatever normalisation was applied before the messages were compared. ## Entity versus resource, and why it matters The stored entity is deliberately narrow: `id`, `indexId`, `projectId`, `launchId`, `message`. It holds **no member list and no count** -- membership lives in the link between items and clusters, and `matchedTests` is derived when the list is read. That is why the count you see is always current for the launch's present state, and why the entity is cheap to rewrite when clustering is run again. So when you read a cluster in an integration, hold on to `launchId` plus `message`, treat `matchedTests` as the health signal, and treat `id` as a handle valid only for as long as this launch's clusters are not regenerated.