Entity List API

The Entity List API provides access to a paginated list of entities and supports filtering and sorting based on risk-related criteria.

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