Entity List API

Overview

The Entity List API is a RESTful endpoint that enables you to retrieve and manage entity data through the GET /api/entity_list endpoint. The API provides comprehensive access to entity information with built-in support for pagination, filtering, and sorting capabilities.

Key features

The Entity List API offers the following capabilities:

Retrieve entities in a paginated format for efficient data handling
Filter entities by risk score thresholds, recent risk, and username
Sort results by risk score or anomaly score

Query parameters

The API accepts several query parameters to control data retrieval and filtering:

Table 1. Query parameters
Parameter	Type	Default	Description
`limit`	integer	50	Maximum number of entities returned in a single request. Valid range: 1–1000. A maximum of 1000 entities per request is allowed.
`offset`	integer	0	Number of entities to skip before returning results. Used for pagination. Values less than 0 are treated as 0.
`risk_score_min`	float	N/A	Returns entities with a risk score greater than or equal to the specified value. Used to identify higher-risk entities. Cannot be used together with `risk_score_max`.
`risk_score_max`	float	N/A	Returns entities with a risk score less than or equal to the specified value. Used to identify lower-risk entities. Cannot be used together with `risk_score_min`.
`risk_score`	float	N/A	Same as `risk_score_min`. Returns entities with a risk score greater than or equal to the specified value.
`recent_risk`	float	N/A	Returns entities whose most recent risk score (`latest_risk`) is greater than or equal to the specified value.
`username`	string	N/A	Returns entities associated with the specified username.
`sortBy`	string	N/A	Sorts the returned entities. Supported values: `risk` (sort by risk score) and `anomalyScore` (sort by aggregated anomaly score). When `anomalyScore` is specified, the response includes the `total_sum_risk` field for each entity.

Filtering rules

When using filter parameters, the following rules apply:

risk_score_min and risk_score_max are mutually exclusive and cannot be used in the same request.
Multiple filter parameters can be combined to further refine results.

Sorting options

The API supports two sorting methods:

Table 2. Sorting options
Value	Description
`risk`	Sort entities by risk score.
`anomalyScore`	Sort entities by aggregated anomaly score and include `total_sum_risk` in the response.

Pagination

Use the following parameters to navigate large result sets:

limit – Number of records returned per request
offset – Starting position of the result set

Response structure

The API returns the following information:

Entity details
Risk-related metrics
Total number of matching entities
Pagination information (limit and offset)

When sorting by anomaly score, an additional aggregated risk metric is included in the response.

Response example

The following example shows a typical API response:

{
  "risk_threshold": 50.0,
  "entities": [
    {
      "entity_id": 12345,
      "username": "john.doe",
      "risk_score": 78.5,
      "latest_risk": 82.0,
      "total_sum_risk": 156.3
    },
    {
      "entity_id": 12346,
      "username": "jane.smith",
      "risk_score": 65.2,
      "latest_risk": 68.7,
      "total_sum_risk": 121.8
    }
  ],
  "total_count": 250,
  "limit": 50,
  "offset": 0
}

The response fields include:

risk_threshold indicates the effective risk threshold applied to the query.
entities contains the list of matching entities.
total_sum_risk is included only when sortBy=anomalyScore.
total_count represents the total number of entities matching the specified filters.
limit and offset provide pagination information for the current result set.

Error handling

The API returns standard HTTP status codes:

200 OK – Request successful
400 Bad Request – Invalid request parameters
500 Internal Server Error – Unexpected server error