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

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 or 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

cluster_id

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 or Batch Verify response where the VPA is clustered.

Request Headers

Authorization

string

required

Your API key, passed as a Bearer token: Authorization: Bearer YOUR_API_KEY

Request Example

cURL

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.

{
  "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

cluster_id

string

The unique identifier for this cluster (e.g., MC-2104). Matches the ID you supplied in the path.

size

integer

The total number of VPAs currently assigned to this cluster.

created_at

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.

last_updated

string

ISO 8601 timestamp of the most recent update to the cluster, such as a new member being added or new evidence being captured.

risk_category

string

The dominant risk category for this cluster. One of: mule, gambling, phishing, scam, nbfc_impersonation.

confidence

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.

members

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.

Show member object fields

members[].upi

string

The UPI VPA of this cluster member.

members[].confidence

float

The individual confidence score for this member VPA, between 0.0 and 1.0.

members[].first_seen

string

ISO 8601 timestamp of when this specific VPA first appeared in FraudTrace intelligence sources.

top_sources

array

An array of the most significant evidence sources associated with this cluster, ranked by how many cluster members they reference.

Show top_sources object fields

top_sources[].url

string

The URL of the source page where cluster members were observed.

top_sources[].category

string

The category of the source. One of: gambling, phishing, scam, telegram.

top_sources[].member_count

integer

The number of cluster members that appear on this source.

total_evidence_count

integer

The total number of distinct evidence items across all members and all sources in this cluster.

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

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.

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.

Overview

MuleTrace

CyberTrace

Mobile Trace

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

Endpoint

Path Parameters

Request Headers

Request Example

Response

Response Fields

Error Codes

Use Case

​Endpoint

​Path Parameters

​Request Headers

​Request Example

​Response

​Response Fields

​Error Codes

​Use Case

Endpoint

Path Parameters

Request Headers

Request Example

Response

Response Fields

Error Codes

Use Case