find

Retrieves all multi-account associations detected within a specific project. This endpoint returns a paginated list of users who have been identified as operating multiple accounts, helping you detect and prevent fraud, abuse, and policy violations.

Endpoint

GET {base_url}/api/v1/{account_id}/projects/{project_id}/multiaccounts

Authentication

Requires API key authentication:

Authorization: Bearer {api_key}

Path Parameters

Query Parameters

This endpoint supports pagination parameters to navigate through large result sets:

• See Pagination query parameters for details on first, after, last, before parameters

Response Structure

The response follows a cursor-based pagination pattern with the following structure:

{
  "edges": [
    {
      "cursor": "string",
      "node": {
        "groupId": "string",
        "accountId": "string",
        "siteKey": "string",
        "createdAt": "string (epoch milliseconds)"
      }
    }
  ],
  "pageInfo": {
    "hasPreviousPage": boolean,
    "hasNextPage": boolean,
    "startCursor": "string | null",
    "endCursor": "string | null",
    "total": integer
  },
  "attributes": {}
}

Response Fields

edges (array): Contains the multi-account records

• cursor (string): Pagination cursor for this record
• node (object): The multi-account data
  • groupId (string): Identifier of the group of linked accounts
  • accountId (string): The BotBye account identifier
  • siteKey (string): The site/project key where the multi-account was detected
  • createdAt (string): When the multi-account association was first detected, epoch milliseconds

pageInfo (object): Pagination metadata

• hasPreviousPage (boolean): Whether there are more results before the current page
• hasNextPage (boolean): Whether there are more results after the current page
• startCursor (string | null): Cursor pointing to the first item in the current page
• endCursor (string | null): Cursor pointing to the last item in the current page
• total (integer): Total number of multi-account associations found

attributes (object): Additional metadata (typically empty)

Example Response

{
  "edges": [
    {
      "cursor": "YXJyYXljb25uZWN0aW9uOjA=",
      "node": {
        "groupId": "0198c39a-6f1b-7c4e-9a2d-5e8f10b3c7d4",
        "accountId": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d",
        "siteKey": "0198c39a-4d80-7a11-b3c2-6f5e8d9a1b02",
        "createdAt": "1723905130000"
      }
    },
    {
      "cursor": "YXJyYXljb25uZWN0aW9uOjE=",
      "node": {
        "groupId": "0198c39a-7a2c-7f31-8b6e-2d4c9a71e055",
        "accountId": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d",
        "siteKey": "0198c39a-4d80-7a11-b3c2-6f5e8d9a1b02",
        "createdAt": "1723972542000"
      }
    }
  ],
  "pageInfo": {
    "hasPreviousPage": false,
    "hasNextPage": true,
    "startCursor": "YXJyYXljb25uZWN0aW9uOjA=",
    "endCursor": "YXJyYXljb25uZWN0aW9uOjE=",
    "total": 47
  },
  "attributes": {}
}

Use Cases

• Fraud Detection: Identify users creating multiple accounts to abuse promotions or referral programs
• Ban Evasion Detection: Detect users creating new accounts after being banned
• Policy Enforcement: Enforce terms of service that limit users to single accounts
• Abuse Prevention: Prevent vote manipulation, review fraud, or other multi-account abuse
• Security Auditing: Review all multi-account associations for security analysis
• User Behavior Analysis: Understand patterns of legitimate vs. fraudulent multi-account usage

Pagination Example

To retrieve the next page of results, use the endCursor value:

GET {base_url}/api/v1/{account_id}/projects/{project_id}/multiaccounts?after=YXJyYXljb25uZWN0aW9uOjE=&first=20

Important Notes

• The same groupId appearing multiple times indicates multiple accounts linked to the same user
• createdAt timestamp indicates when BotBye first detected the multi-account association
• Use pagination to efficiently process large numbers of multi-account detections
• Consider implementing automated workflows to handle detected multi-accounts (e.g., flagging for review, automatic blocking)
• False positives can occur in shared device scenarios (e.g., public computers, family devices)

Accepted permissions Project → Multi Account → Multi account

Token scope Multi Account View