list | Botbye | Documentation

Retrieves a paginated list of project users whose credentials were entered on a phishing site, deduplicated to one row per user.

Endpoint

GET {base_url}/api/v1/{account_id}/projects/{project_id}/compromised-users

Authentication

Requires API key authentication:

Authorization: Bearer {api_key}

Path Parameters

Parameter	Type	Required	Description
`account_id`	string	Yes	Your unique BotBye account identifier
`project_id`	string	Yes	The project to retrieve compromised users for

Query Parameters

Pagination: cursor-based (cursor, limit). By default limit is 20, max 100.
Filtering: where supports filtering on the available fields (e.g. phishing_origin).
Ordering: order_by — results are keyed by account_id.

Response Structure

Cursor-based pagination. Each node is one compromised user:

Field	Type	Description
`id`	string	Stable node id, `"{accountId}:{projectId}"` (unique within the project)
`accountId`	string	The end-user account id as reported by the integration
`phishingOrigin`	string	Origin of the most recent compromised login (latest wins)
`lastLoginAt`	string	Timestamp (epoch millis) of the most recent compromised login

pageInfo carries hasPreviousPage, hasNextPage, startCursor, endCursor and total (the distinct number of compromised users).

Use Cases

Incident response: identify which users to force-reset after a phishing campaign.
Customer notification: surface affected accounts to warn end users.
Campaign analysis: group compromised users by the phishing origin that captured them.

Accepted permissions Project → ATO info → ATO info

Token scope ATO Info View

# Get Compromised Users Retrieves a paginated list of project users whose credentials were entered on a phishing site, deduplicated to one row per user. ## Endpoint ``` GET {base_url}/api/v1/{account_id}/projects/{project_id}/compromised-users ``` ## Authentication Requires API key authentication: ``` Authorization: Bearer {api_key} ``` ## Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `account_id` | string | Yes | Your unique BotBye account identifier | | `project_id` | string | Yes | The project to retrieve compromised users for | ## Query Parameters - **Pagination**: cursor-based (`cursor`, `limit`). By default `limit` is 20, max 100. - **Filtering**: `where` supports filtering on the available fields (e.g. `phishing_origin`). - **Ordering**: `order_by` — results are keyed by `account_id`. ## Response Structure Cursor-based pagination. Each `node` is one compromised user: | Field | Type | Description | | --- | --- | --- | | `id` | string | Stable node id, `"{accountId}:{projectId}"` (unique within the project) | | `accountId` | string | The end-user account id as reported by the integration | | `phishingOrigin` | string | Origin of the most recent compromised login (latest wins) | | `lastLoginAt` | string | Timestamp (epoch millis) of the most recent compromised login | **pageInfo** carries `hasPreviousPage`, `hasNextPage`, `startCursor`, `endCursor` and `total` (the distinct number of compromised users). ## Use Cases - **Incident response**: identify which users to force-reset after a phishing campaign. - **Customer notification**: surface affected accounts to warn end users. - **Campaign analysis**: group compromised users by the phishing origin that captured them. > **Accepted permissions** > `Project → ATO info → ATO info` > > **Token scope** > `ATO Info View`

Authentication

X-Api-Keystring

Personal access token. Create it in your BotBye account under Profile → Personal Access Tokens, tick the scopes the endpoints you call require (see each endpoint’s Token scope), and send the token in the X-Api-Key request header. A token works only for the account it was created in.

Personal access token. Create it in your BotBye account under **Profile → Personal Access Tokens**, tick the scopes the endpoints you call require (see each endpoint's **Token scope**), and send the token in the `X-Api-Key` request header. A token works only for the account it was created in.

Path parameters

account_idstringRequired

project_idstringRequired

Query parameters

cursorstringOptional

(Optional): a cursor for pagination.

after (string): Pointer to the item after which the items are to be retrieved.
before (string): Pointer to the item before which the items are to be retrieved.

(Optional): a cursor for pagination. - `after` (string): Pointer to the item after which the items are to be retrieved. - `before` (string): Pointer to the item before which the items are to be retrieved.

wherestringOptional

(Optional): is used to create conditions for data filtering. It can be used to create simple conditions (leaf nodes) as well as compound logical expressions (branch nodes).

predicate (string): The filtering condition (e.g., gte, lte, eq for a leaf or and, or for a branch). Possible values [[#Predicate]]
opearands (string): A list of nested conditions (used only for branches, such as and, or).
fieldPath (string): The field to which the filtering condition is applied (used only for a leaf. Each entity has its own fieldPath list).
value (string): The value to compare against the field (used only for a leaf).

(Optional): is used to create conditions for data filtering. It can be used to create simple conditions (leaf nodes) as well as compound logical expressions (branch nodes). - `predicate` (string): The filtering condition (e.g., `gte`, `lte`, `eq` for a leaf or `and`, `or` for a branch). Possible values [[#Predicate]] - `opearands` (string): A list of nested conditions (used only for branches, such as `and`, `or`). - `fieldPath` (string): The field to which the filtering condition is applied (used only for a leaf. Each entity has its own fieldPath list). - `value` (string): The value to compare against the field (used only for a leaf).

order_bystringOptional

(Optional): property by which to order by.

fieldPath (string): name of order field.
direction (string): ASC or DESC

(Optional): property by which to order by. - `fieldPath` (string): name of order field. - `direction` (string): `ASC` or `DESC`

limitstringOptional

(Optional): specifies the maximum number of results to return in a single response. By default - 20, max - 100.

Response headers

Content-Lengthinteger

ConnectionstringOptional

Response

success

edgeslist of objects

pageInfoobject

attributesobject

Errors

400

Bad Request Error

Retrieves a paginated list of project users whose credentials were entered on a phishing site, deduplicated to one row per user.

Endpoint

GET {base_url}/api/v1/{account_id}/projects/{project_id}/compromised-users

Authentication

Requires API key authentication:

Authorization: Bearer {api_key}

Path Parameters

Parameter	Type	Required	Description
`account_id`	string	Yes	Your unique BotBye account identifier
`project_id`	string	Yes	The project to retrieve compromised users for

Query Parameters

Pagination: cursor-based (cursor, limit). By default limit is 20, max 100.
Filtering: where supports filtering on the available fields (e.g. phishing_origin).
Ordering: order_by — results are keyed by account_id.

Response Structure

Cursor-based pagination. Each node is one compromised user:

Field	Type	Description
`id`	string	Stable node id, `"{accountId}:{projectId}"` (unique within the project)
`accountId`	string	The end-user account id as reported by the integration
`phishingOrigin`	string	Origin of the most recent compromised login (latest wins)
`lastLoginAt`	string	Timestamp (epoch millis) of the most recent compromised login

pageInfo carries hasPreviousPage, hasNextPage, startCursor, endCursor and total (the distinct number of compromised users).

Use Cases

Incident response: identify which users to force-reset after a phishing campaign.
Customer notification: surface affected accounts to warn end users.
Campaign analysis: group compromised users by the phishing origin that captured them.

Accepted permissions Project → ATO info → ATO info

Token scope ATO Info View