> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fraudtraceai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /v1/verify/upi/cluster/{id} — Mule Cluster Details

> Retrieve the full details of a mule cluster by ID, including all member VPAs, per-member confidence scores, and aggregated evidence sources.

The Cluster Lookup endpoint returns the complete picture of a known mule cluster: every member VPA with its individual confidence score and first-seen timestamp, the top evidence sources that link the cluster to fraud activity, and aggregate metadata such as cluster size and last updated time. You get a `cluster_id` from the [Verify UPI](/api-reference/muletrace/verify-upi) or [Batch Verify](/api-reference/muletrace/batch-verify) endpoints whenever a VPA belongs to a known group — use that ID here to understand the full scope of the network before taking action.

## Endpoint

**`GET https://api.fraudtraceai.com/v1/verify/upi/cluster/{cluster_id}`**

***

## Path Parameters

<ParamField path="cluster_id" type="string" required>
  The unique identifier for the mule cluster you want to look up (e.g., `MC-2104`). You receive this value in the `cluster_id` field of any [Verify UPI](/api-reference/muletrace/verify-upi) or [Batch Verify](/api-reference/muletrace/batch-verify) response where the VPA is clustered.
</ParamField>

***

## Request Headers

<ParamField header="Authorization" type="string" required>
  Your API key, passed as a Bearer token: `Authorization: Bearer YOUR_API_KEY`
</ParamField>

***

## Request Example

```bash cURL theme={null}
curl https://api.fraudtraceai.com/v1/verify/upi/cluster/MC-2104 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

***

## Response

The response body describes the cluster as a whole, lists every known member VPA, and surfaces the top evidence sources contributing to the cluster's risk classification.

```json theme={null}
{
  "cluster_id": "MC-2104",
  "size": 7,
  "created_at": "2025-11-14T08:22:00Z",
  "last_updated": "2026-04-01T16:45:00Z",
  "risk_category": "mule",
  "confidence": 0.96,
  "members": [
    { "upi": "xxxxx@ybl",        "confidence": 0.94, "first_seen": "2025-11-14T08:22:00Z" },
    { "upi": "yyyy7421@paytm",   "confidence": 0.98, "first_seen": "2025-11-20T11:00:00Z" },
    { "upi": "zzz9801@okaxis",   "confidence": 0.88, "first_seen": "2025-12-01T09:30:00Z" }
  ],
  "top_sources": [
    { "url": "https://bet-quick-in.com",  "category": "gambling", "member_count": 5 },
    { "url": "https://spinwin-247.net",   "category": "gambling", "member_count": 3 }
  ],
  "total_evidence_count": 14
}
```

### Response Fields

<ResponseField name="cluster_id" type="string">
  The unique identifier for this cluster (e.g., `MC-2104`). Matches the ID you supplied in the path.
</ResponseField>

<ResponseField name="size" type="integer">
  The total number of VPAs currently assigned to this cluster.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when this cluster was first created in the FraudTrace intelligence database — typically the timestamp of the earliest member's first appearance.
</ResponseField>

<ResponseField name="last_updated" type="string">
  ISO 8601 timestamp of the most recent update to the cluster, such as a new member being added or new evidence being captured.
</ResponseField>

<ResponseField name="risk_category" type="string">
  The dominant risk category for this cluster. One of: `mule`, `gambling`, `phishing`, `scam`, `nbfc_impersonation`.
</ResponseField>

<ResponseField name="confidence" type="float">
  The cluster-level confidence score between `0.0` and `1.0`. This is an aggregate signal derived from all member-level confidence scores and the breadth of evidence across the cluster. Higher values indicate a more firmly established mule network.
</ResponseField>

<ResponseField name="members" type="array">
  An array of all VPAs that belong to this cluster. Use this list to build a watchlist or block-list covering the full network.

  <Expandable title="member object fields">
    <ResponseField name="members[].upi" type="string">
      The UPI VPA of this cluster member.
    </ResponseField>

    <ResponseField name="members[].confidence" type="float">
      The individual confidence score for this member VPA, between `0.0` and `1.0`.
    </ResponseField>

    <ResponseField name="members[].first_seen" type="string">
      ISO 8601 timestamp of when this specific VPA first appeared in FraudTrace intelligence sources.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="top_sources" type="array">
  An array of the most significant evidence sources associated with this cluster, ranked by how many cluster members they reference.

  <Expandable title="top_sources object fields">
    <ResponseField name="top_sources[].url" type="string">
      The URL of the source page where cluster members were observed.
    </ResponseField>

    <ResponseField name="top_sources[].category" type="string">
      The category of the source. One of: `gambling`, `phishing`, `scam`, `telegram`.
    </ResponseField>

    <ResponseField name="top_sources[].member_count" type="integer">
      The number of cluster members that appear on this source.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total_evidence_count" type="integer">
  The total number of distinct evidence items across all members and all sources in this cluster.
</ResponseField>

***

## Error Codes

| HTTP Status                 | Meaning                                                                                                |
| --------------------------- | ------------------------------------------------------------------------------------------------------ |
| `400 Bad Request`           | The `cluster_id` path parameter is missing or not in the expected format.                              |
| `401 Unauthorized`          | The `Authorization` header is missing or the API key is invalid.                                       |
| `404 Not Found`             | No cluster exists with the given `cluster_id`.                                                         |
| `429 Too Many Requests`     | You have exceeded your rate limit. Check the `Retry-After` header and retry after the indicated delay. |
| `500 Internal Server Error` | An unexpected error occurred on the FraudTrace side. Retry with exponential back-off.                  |

***

## Use Case

<Tip>
  When a VPA check returns a `cluster_id`, call this endpoint to pull every member of the cluster and add them all to your watchlist or block-list in one step. Because mule networks operate as coordinated groups, blocking a single VPA while leaving the rest of the cluster active significantly reduces the effectiveness of your controls. Monitoring the `last_updated` timestamp lets you detect when a cluster is actively growing — a signal that the network is still operational.
</Tip>

<Info>
  Cluster membership evolves as FraudTrace continuously ingests new intelligence. A VPA that returns `cluster_id: null` today may be assigned to a cluster in a future query once additional evidence links it to a known group. Schedule periodic re-checks for VPAs you are actively monitoring.
</Info>