Activities API¶

Activities API enables users to retrieve audit logs for tracking all events from connected subsystems, system operations, and user actions. This allows customers to integrate data into their own workflows and applications for reporting and investigation purposes.

Additionally, the Activities API introduces two new endpoints to ensure robust and flexible control, and also features improved data filtering capabilities:

Endpoints for flexible access:
Access audit logs using explicit customer and partition endpoints.
- Customer Level Events Endpoint: Retrieve customer level events that are associated with the entire company or customer account, regardless of any specific partition. These events provide a holistic view of activities that impact the company as a whole, such as user group events, partition creation, role creation, company-wide policy updates, or other actions performed at the customer (company) level.
  
  Example:
  - When Role is added to Customer
  - When Role is added to UserGroup
  - When User group is added to Member
  Endpoint:
```
curl -H "Authorization: Bearer $TOKEN" \
    "{{buildingxopenness.env.securityApiUrl}}/sec-activities/v2/customers/$CUSTOMER_ID?page[size]=2"    
```
- Partition Level Events Endpoint: Retrieve events specific to the partition within the company. Partition level events include activities that are associated with a particular partition, such as alarms or user operations that occur within that partition. These events provide detailed visibility into actions and changes that impact only the selected partition, rather than the entire company.
  
  Example:
  - When Alarm triggered in a partition
  - When Access granted for an identity within a partition
  - When a visitor checks out from a partition
  Endpoint:
```
curl -H "Authorization: Bearer $TOKEN" \
        "{{buildingxopenness.env.securityApiUrl}}/sec-activities/v2/partitions/$PARTITION/customers/$CUSTOMER_ID?page[size]=2"
```
For a complete example of how to use this v2 endpoint, see the Quick Start guide.
Data Filtering Capabilities: Easily pinpoint the exact information you need with more powerful and efficient filtering options.

Activity Log Search & Filtering Features¶

Activities API provides free text search and supports multiple filter parameters in the API request to help quickly search specific activities. By combining search and filtering through API parameters, related activities and log data in Activity Log can be efficiently accessed.

filterText:
The filterText parameter in the API works as follows: search text without quotation marks returns activities containing any of the words in any order, while enclosing the search text in quotation marks returns activities that exactly match the entire value in the specified order.

Example for Exact match:

To search for activities that exactly match the phrase "user group":
```
filterText="user group"
```
Sample Response:
```
{
  // ... more fields ...
  "Description": "User group member added in ***************",
  // ... more fields ...
}
```
Example for free text:

To search for activities containing either "user" and "member" in any order.
```
filterText=user member
```
Sample Response:
```
{
  // ... more fields ...
  "Description": "User group member added in ***************",
  // ... more fields ...
}
```
Date range:
The date range filter allows activities to be filtered and viewed within a specific date range. In the API request, use the parameters startDate and endDate to specify the desired range. Both startDate and endDate must be provided together; if only one is given, the request will not be processed and validation will fail. When both are provided, activities are filtered by the specified range.

Note: The date format must be in UTC

Example Date Range Parameters:
```
startDate=2025-09-10T00:00:00.882Z&endDate=2025-12-10T15:36:06.804Z
```
Filter Criteria:
Activities API provides multiple filter parameters in the API request to help refine search results. One or more filter criteria can be specified directly in the API request, such as severity, category, subSystem, and location. Multiple values for a filter can be provided by separating them with commas. Each filter is processed sequentially to progressively refine the results, allowing customization to retrieve the most relevant activity data.

Note: Filter values must match exactly as they appear in the event data, including spaces and capitalization. Filtering is always case-sensitive. For example, severity=low will not match severity=Low.

Example 1:
To filter activities with severity "Low", system as "Building X Accounts", and category as "User operation", your API request parameters would look like:
```
severity=Low&subSystem=Building X Accounts&category=User operation
```
This means the API will first filter activities by severity "Low", then further refine the results to those from the "Building X Accounts" system, and finally narrow down to activities in the "User operation" category.

Example 2: To filter activities with severity "Low" or "High", system as "Building X Accounts" or "Security Manager", and category as "User operation", your API request parameters would look like:
```
severity=Low,High&subSystem=Building X Accounts, Security Manager&category=User operation
```
This means the API will first filter activities by severity "Low" or "High", then further refine the results to those from either the "Building X Accounts" or "Security Manager" system, and finally narrow down to activities in the "User operation" category.
Pagination:
The API supports pagination using the page[size] parameter. The maximum limit for page[size] is 1000 records per page. If not specified, the default value is 1000. To retrieve the next set of records, use the page[cursor] parameter with the value returned in the previous API response. This cursor-based pagination allows efficient handling and navigation of large result sets, enabling seamless retrieval of subsequent pages.

Example Pagination Parameters:
```
page[size]=1000&page[cursor]=693271ec4711b6c3cd7134ee
```

Concepts & Glossary¶

Term	Description
Activity	Is an audit trail for both customer and partition level events from various systems