--- title: Audit Logging slug: audit-logging docTags: createdAt: 2025-08-11T11:13:48.000Z --- Audit logging in Swimlane Turbine records critical actions and events across the system, providing visibility for monitoring, security, and compliance. Audit logs can be retrieved using the API, and users can apply filters to narrow down the results based on account, tenant, and time range. ## Understand the API Log Retrieval Endpoint Audit logs in Swimlane are accessible via two endpoints: - `auditlogs `Endpoint (Recommended): Provides enhanced log data, including pagination and the total number of logs. - `https://.swimlane.app/api/public/audit/account/{account_id}/auditlogs?tenantList=tenantIdList&includeAccount=true&fromdate=2024-10-01T00:00:00Z&todate=2024-10-07T23:59:59Z&pageNumber=1&pageSize=100` - `logs` Endpoint: Retrieves basic log data. Planned for deprecation. - `https://.swimlane.app/api/account/{account_id}/tenant/{tenant_id}/logs` :::hint{type="info"} Only Account Admins can access the Audit Logs. ::: ## Key API Parameters Below are the key parameters that users can specify in their API calls to filter and paginate the audit log results: | Parameter | Description | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `{account_id}` | The unique identifier for the account. Required for all API requests to fetch audit logs. | | `{tenant_id}` | The identifier for the tenant associated with the account. Required for both account-level and tenant-level log retrieval. | | `fromdate `(Optional) | The start date for retrieving logs, in ISO 8601 format. If not provided, the API will default to retrieving logs starting 7 days prior to the current date. Use this parameter in combination with todate to specify a time range. | | `todate` (Optional) | The end date for retrieving logs, in ISO 8601 format. If not provided, the API will retrieve logs up to the current date. Useful when combined with fromdate to define a specific time range for logs. | | `pageNumber `(Optional) | Used for pagination. Specifies the page number of results to retrieve. Defaults to 1. If pageNumber and pageSize exceed a combined result of 10,000 logs, a warning is triggered, and further logs are not retrieved.
**Note:** Audit logs retrieved from Elastic are currently capped at a maximum of 10,000 entries. This means that if more than 10,000 logs exist for the specified time range, only the first 10,000 logs will be returned, and subsequent logs will not be included in the results. Users should apply narrower date ranges or additional filters to retrieve the complete set of logs. | | `pageSize `(Optional) | Specifies how many log entries to return per page. The default and maximum page size is 100. Attempting to specify a pageSize larger than 100 will return an error. Use this in combination with pageNumber to paginate results effectively. | | `tenantList `(Optional) | Lists specific tenants whose logs are to be retrieved. If not specified, logs for all tenants under the account are returned. Combining this with includeAccount provides flexibility in log retrieval. | | `includeAccount `(Optional) | Specifies whether to include account-level logs in the response. Accepts \`true\` to include account logs, or \`false\` to exclude them. The default value is 'true'. For example, setting includeAccount=true with tenantList will return logs for both the account and the tenants. | **Pagination:** The API supports pagination with the \`pageNumber\` and \`pageSize\` parameters. Use \`pageNumber\` to navigate through the pages of results and \`pageSize\` to limit how many entries appear on each page. For example, to retrieve the second page of results with 50 entries per page, use the following request: `GET https://<region>.swimlane.app/api/public/audit/account/{account_id}/tenant/{tenant_id}/auditlogs?pageNumber=2&pageSize=50` :::hint{type="info"} Data retention is limited to 7 days. ::: ## Error Handling Common errors to be aware of: - If you specify a `pageSize` larger than 100, the API will return an error. For example, GET `https://.swimlane.app/api/public/audit/account/{account_id}/tenant/{tenant_id}/auditlogs?pageSize=150.` - **400 Bad Request:** Returned when required parameters (such as \`account\_id\` or \`tenant\_id\`) are missing or invalid. - **403 Forbidden:** Returned if the user does not have permission to access the requested logs. - **500 Internal Server Error:** Indicates a server-side issue. If this occurs, try the request again later. - **Elastic Cap Error:** If you request more than 10,000 logs within a date range, the API will only return the first 10,000 logs and ignore the rest. ## Authentication for Audit Log API The Audit Log API in Swimlane Turbine supports authentication exclusively via **Personal Access Tokens (PATs)**. Only **account admin**s have access to this API. **Prerequisites:** - Ensure you have **admin access** to the Swimlane Turbine account. - Generate a **Personal Access Token (PAT)** from your Swimlane account. Step 1: Generate a Personal Access Token (PAT) 1. Log in to **Swimlane**. 2. Click on your **Profile & User Settings** in the top-right corner. 3. Navigate to **Personal Access Token**. 4. Click **Generate New Token**. 5. Copy the token **immediately**, as it won't be visible again after closing the dialog. Step 2: Authenticate and Retrieve Audit Logs Using cURL To access the **Audit Log API**, use the following **cURL** request with your **Personal Access Token (PAT)**: **Example cURL Request:** ```text curl -X GET "https://.swimlane.app/api/public/audit/account/{account_id}/auditlogs" \ -H "Private-Token: " ``` - Replace `` with your Swimlane instance’s region. - Replace `{account_id}` with your account’s ID. - Replace `` with your actual personal access token (PAT) used in the Private-Token header. ## Audit Logs Implementation Examples **Scenario 1: Get log for the account and tenants** - **Description:** Retrieves logs when all query parameters are not provided. The API will return logs for the account and all tenants with default pagination. - **Example Request:** - `GET https://hostname/api/public/audit/account/{account_id}/auditlogs` - **Result:** Logs are returned with default time range, pagination (page 1), and page size (100). - **Output Example:** :::CodeblockTabs{indent="2"} ```text { "totalCount": 1250, "next": "/auditlogs?pageNumber=2&pageSize=100", "previous": null, "auditlogs": [ { "eventTime": "2024-10-28T08:41:48Z", "user": "admin@swimlane.com", "userId": "12345", "category": "Playbook", "actionType": "Create", "description": "Admin created playbook 'Incident Response'", "eventOutcome": "Success" } ] } ``` ::: **Scenario 2: Get tenant logs for a specific time range** - **Description:** Retrieves logs when tenantList is specified and includeAccount is set to true. Filters are applied using fromdate and todate. - **Example Request:** - `GET https://hostname/api/public/audit/account/{account_id}/auditlogs?tenantList=tenantIdList&includeAccount=true&fromdate=2024-10-01T00:00:00Z&todate=2024-10-07T23:59:59Z&pageNumber=1&pageSize=100` - **Result:** Logs related to the specified tenants and time range are returned, with pagination details and totalCount. - **Output Example:** :::CodeblockTabs{indent="2"} ```text { "totalCount": 4113, "next": "/auditlogs?tenantList=tenantIdList&includeAccount=true&fromdate=2024-10-01T00:00:00Z&todate=2024-10-07T23:59:59Z&pageNumber=2&pageSize=100", "previous": null, "auditlogs": [ { "eventTime": "2024-10-07T08:41:48Z", "user": "user@tenant.com", "userId": "56789", "category": "UserManagement", "actionType": "Retrieve", "description": "User read details for userId: 56789", "eventOutcome": "Success" } ] } ``` ::: **Scenario 3: Warning for Exceeding 10K Logs** - **Description:** Retrieves logs when pageSize and pageNumber multiply to exceed the 10,000 logs cap, triggering a warning message. - **Example Request:** - `GET https://hostname/api/public/audit/account/{account_id}/auditlogs?pageNumber=101&pageSize=100` - **Result:** The API returns a warning indicating the limit of 10,000 logs has been exceeded. - **Output Example:** :::CodeblockTabs{indent="2"} ```text { "error": { "message": "Cannot retrieve more than 10,000 logs. Please apply narrower filters.", "code": 400 } ``` ::: **Scenario 4: Tenant log with no Account level logs** - **Description:** Retrieves logs when tenantList is specified and includeAccount is set to false. Remaining parameters are not specified. - **Example Request:** - `GET https://hostname/api/public/audit/account/{account_id}/auditlogs?tenantList=tenantIdList&includeAccount=false` - **Result:** Only tenant-level logs are returned for the last 7 days. - **Output Example:** :::CodeblockTabs{indent="2"} ```text { "totalCount": 532, "next": "/auditlogs?tenantList=tenantIdList&pageNumber=2&pageSize=100", "previous": null, "auditlogs": [ { "eventTime": "2024-10-20T08:41:48Z", "user": "tenantUser@tenant.com", "userId": "98765", "category": "Record", "actionType": "Update", "description": "User updated record 'Incident-234'", "eventOutcome": "Success" } ] } ``` ::: **Scenario 5: Logs with Pagination and Missing Tenant Information** - **Description:** Retrieves logs when tenantList, fromDate, and toDate are missing, but pagination is defined. - **Example Request:** - `GET https://hostname/api/public/audit/account/{account_id}/auditlogs?pageNumber=2&pageSize=100` - **Result:** Logs related to the account and tenants for the default time range are returned with the specified pagination. - **Output Example:** :::CodeblockTabs{indent="2"} ```text { "totalCount": 750, "next": "/auditlogs?pageNumber=3&pageSize=100", "previous": "/auditlogs?pageNumber=1&pageSize=100", "auditlogs": [ { "eventTime": "2024-10-21T08:41:48Z", "user": "user@account.com", "userId": "23456", "category": "AssetManagement", "actionType": "Delete", "description": "User deleted asset 'Laptop-001'", "eventOutcome": "Success" } ] } ``` ::: **Scenario 6: Logs with Date Range Filters and Missing Pagination** - **Description:** Retrieves logs when fromdate and todate are specified, but tenantList and pagination details are missing. - **Example Request:** - `GET https://hostname/api/public/audit/account/{account_id}/auditlogs?fromdate=2024-10-01T00:00:00Z&todate=2024-10-07T23:59:59Z` - **Result:** All logs related to the account and tenants for the specified date range are returned. - **Output Example:** :::CodeblockTabs{indent="2"} ```text { "totalCount": 1600, "next": "/auditlogs?pageNumber=2&pageSize=100", "previous": null, "auditlogs": [ { "eventTime": "2024-10-05T08:41:48Z", "user": "user@company.com", "userId": "87654", "category": "Settings", "actionType": "Read", "description": "User read security settings", "eventOutcome": "Success" } ] } ``` ::: **Scenario 7: Logs with All Query Parameters Specified** - **Description:** Retrieves logs when all query parameters (tenantList, includeAccount, fromdate, todate, pageNumber, and pageSize) contain values. - **Example Request:** - `GET https://hostname/api/public/audit/account/{account_id}/auditlogs?tenantList=tenantIdList&includeAccount=true&fromdate=2024-10-01T00:00:00Z&todate=2024-10-07T23:59:59Z&pageNumber=1&pageSize=100` - **Result:** Logs related to the account and tenants, filtered by the specified parameters, are returned with pagination details and total count. - **Output Example:** :::CodeblockTabs{indent="2"} ```text { "totalCount": 4200, "next": "/auditlogs?tenantList=tenantIdList&includeAccount=true&fromdate=2024-10-01T00:00:00Z&todate=2024-10-30T23:59:59Z&pageNumber=2&pageSize=100", "previous": null, "auditlogs": [ { "eventTime": "2024-10-07T08:41:48Z", "user": "admin@swimlane.com", "userId": "12345", "category": "Playbook", "actionType": "Create", "description": "Admin created playbook 'Incident Response'", "eventOutcome": "Success" } ] } ``` ::: Use this table to further understand the event types logged in audit logs: :::hint{type="info"} Depending on the event type, some fields may not be present. ::: | Audit Logs | Definition | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | EventTime | The date and time when the event occurred in ISO 8601 format. | | User | The unique identifier (email) of the authenticated user. If the event is triggered by the system or automation, the field will be "Null." | | UserId | The unique identifier (GUID) for the user. | | Category | Defines the functional areas, such as Settings, Applications, User Management, Record, Solutions, Playbook, UserManagement, Sensor, and AccountManagement. | | Description | A short description of the event, including what action was taken and what data was accessed or modified. | | TenantId | Any action performed under a specific tenant. | | AccountId | For account-level operations (user management) the AccountId is required. AccountId is not required when TenantId is provided. | | SourceIp | The IP address of the client/user. | | UserAgent | User-agent header responsible for making the request for non-system access. | | ActionType | Describes the type of action that occurred, such as Create, Update, Delete, Read, Login, Logout, and UserAction. | | Id | ID of the value being created, updated, deleted, or read, when available. | | NewValue | New field value if the change or addition is atomic. For model updates, the new updated model in JSON format. | | EventOutcome | Either "Success" or "Failure". | The following table lists the event/action category and their details events/actions. | Event/Action Category | Action Type | | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | Login /Logout | Login /Logout via Email | | | Login /Logout via SAML/SSO | | | Failed login for normal and SSO users | | | MFA changes (for example, switching it off) | | | Failed MFA | | | Password changes | | | Force SSO login changes | |   |   | | User Management | Create, update, delete -> users, groups and roles | | | Changes in groups and roles for a user | | | Permission changes on groups, roles | | | Enable and disable 2FA at user level | | | Exempt force SSO for user | | | Create and delete PAT token | |   |   | | Playbook/solution | User created a playbook | | | User updated a playbook | | | User deleted a playbook | | | User triggered playbook runs | | | Create a playbook with a webhook | | | Create a playbook with a schedule | | | Create a playbook with a record action | | | Install a solution | | | Update a solution | | | Delete a solution | | | Import an SSP | | | Install a component | | | Enable disable playbooks | | | Update action | | | CRUD triggers | |   |   | | Record (exclude data ingested by integrations or updated by playbooks) | Create a record | | | Read a record | | | Update a record | | | Delete a record | |   |   | | Asset Management | Create an asset | | | Read an asset | | | Update an asset | | | Delete an asset | |   |   | | Connectors | Install a connector | | | Update or upgrade connector | | | Delete a connector | |   |   | | Webhooks | Create, update and delete webhooks | |   |   | | Settings | Authentication configuration: CRUD of MFA, SAML settings | | | Enable and Disable SAML | | | Enable and Disable 2FA | | | Password settings update | | | Enable and Disable Directory services | | | Changes to login, authentication and password policy settings, proxy settings | | | Changes to advanced configuration settings | | | Email settings | | | Update tenant specific settings like tim zone , email , connector Key | |   |   | | Tenant Management | Create a Tenant | | | Update tenant feature flags | | | Update tenant limit | | | Delete tenant | | | Revoke user access to a tenant | |   |   | | Account Management | CRUD account | | | Update account feature flags | |   |   | | Applications | Schedule reports | | | CRUD on report | | | CRUD on dashboard | | | CRUD on application | | | CRUD on workspace | | | Update application settings | | | CRUD correlation | | | Field level permission updates | |   |   | | Remote Agents
 
  | Update remote agents | | | Create agents | | | Delete agents | ### Audit Log Category Examples **ActionType Example of a Read Audit Event** ```text { "EventTime": "2025-02-25T15:48:14.7436951Z", "User": "abc.def@swimlane.com", "UserId": "e89asd4c-v3as-4e5d-99f1-049c4cf0f902", "Category": "User Management", "LogSource": "api", "LogType": "Audit", "Description": "ABC DEF read application user e89asd4c-v3as-4e5d-99f1-049c4cf0f902", "AccountId": "30ad6dcd-bd77-4f2d-bfea-baddb677261f", "TenantId": "fd336516-khk0-4b92-853a-55748ea86248", "SourceIp": "::ffff:10.64.85.159", "UserAgent": "axios\/1.7.7", "ActionType": "Read", "Id": "e89edf4c-a4de-4e5d-99f1-049c4cf0f902", "EventOutcome": "Success", "Endpoint": "\/user\/authorize", "IsAdmin": "True", "AuthenticationType": "JWT" } ``` **Category Example: Playbook** ```text { "EventTime": "2025-02-25T15:32:56.2203069Z", "User": "abc.def@swimlane.com", "UserId": "e89asd4c-v3as-4e5d-99f1-049c4cf0f902", "Category": "Playbook", "LogSource": "api", "LogType": "Audit", "Description": "ABC DEF deleted ingestion rule by application ID aH3Sk1eHoF0n03soC", "AccountId": "30ad6dcd-bd77-4f2d-bfea-baddb677261f", "TenantId": "fd336516-khk0-4b92-853a-55748ea86248", "SourceIp": "8.23.564.38", "UserAgent": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit\/537.36 (KHTML, like Gecko) HeadlessChrome\/133.0.0.0 Safari\/537.36", "ActionType": "Delete", "EventOutcome": "Success", "Endpoint": "\/app\/aH3Sk1eHoF0n03soC", "IsAdmin": "True", "AuthenticationType": "JWT" } ``` **Create Remote Agents:** ```text { "EventTime": "2025-02-27T09:28:52.870Z", "User": "asds@gmail.com", "UserId": "17ee487f-d79a-8s2h-b66b-bdd093952897", "Category": "Node", "Description": "asds@gmail.com Updated node 67c02bb1b84d184e62d823e5", "ActionType": "Update", "Id": "67c02bb1b84d184e62d823e5", "SourceIp": "8.23.564.38", "UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36", "EventOutcome": "Success", "Endpoint": "/v1/agents/67c02bb1b84d184e62d154e5", "IsAdmin": true, "AuthenticationType": "JWT" } ``` **Update Remote Agents:** ```text { "EventTime": "2025-02-27T09:28:52.870Z", "User": "asds@gmail.com", "UserId": "17ee487f-d79a-8s2h-b66b-bdd093952897", "Category": "Node", "Description": "asds@gmail.com Updated node 67c02bb1b84d184e62d823e5", "ActionType": "Update", "Id": "67c02bb1b84d184e62d823e5", "SourceIp": "8.23.564.38", "UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36", "EventOutcome": "Success", "Endpoint": "/v1/agents/67c02bb1b84d184e62d154e5", "IsAdmin": true, "AuthenticationType": "JWT" } ``` **Delete Remote Agent:** ```text { "EventTime": "2025-02-26T15:50:18.714Z", "User": "asds@gmail.com", "UserId": "17ee487f-d79a-8s2h-b66b-bdd093952897", "Category": "Node", "Description": "asds@gmail.com Updated node 67c02bb1b84d184e62d823e5", "ActionType": "Delete", "Id": "67bf29f50ee4512d80126a3a", "SourceIp": "8.23.564.38", "UserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36", "EventOutcome": "Success", "Endpoint": "/v1/agents/67c02bb1b84d184e62d154e5", "IsAdmin": true, "AuthenticationType": "JWT" } ``` ## Forwarding Audit Logs to a SIEM or External Log Aggregator You can retrieve Swimlane Turbine audit logs using the `auditlogs` API endpoint. The endpoint provides access to audit events for monitoring, compliance, and export purposes. Audit logs are retained in Turbine for **7 days only**. If you require longer retention you must retrieve the logs through the API and store them in their own SIEM or logging platform. :::hint{type="info"} - Turbine exposes audit logs through a pull-based API. - Turbine does not automatically push audit logs to external systems. ::: ### Storing Audit Logs in a SIEM You can call the auditlogs endpoint and store the returned data in their internal SIEM for as long as required. ```bash curl -X GET "https://.swimlane.app/api/public/audit/account/{account_id}/auditlogs" \ -H "Private-Token: " ``` Typically, you can configure your SIEM or log collection system to periodically retrieve logs and retain them externally beyond the 7-day Turbine limit. ### Elastic Integration In case of using the Elastic stack, you can leverage the Swimlane integration package available through Elastic: [https://github.com/elastic/integrations/tree/main/packages/swimlane ](https://github.com/elastic/integrations/tree/main/packages/swimlane) This integration supports ingesting Swimlane log data into Elastic. You must still retrieve audit logs through the API before storing them in their own Elastic deployment for long-term retention. ### Audit Logs vs System Logs Audit logs record user and administrative activity within Turbine and are retrieved using the Audit Log API. System logs (application/container logs) are emitted via stdout and are available through the Kubernetes log stream. Collect these logs using your infrastructure-level logging tools. ## Best Practices for Audit Log Retrieval Follow these best practices to optimize your use of the Swimlane audit logging API and ensure you retrieve accurate, comprehensive data efficiently. - **Use Date Filters to Narrow the Scope:** Always apply specific date filters using the fromdate and todate parameters to avoid retrieving unnecessary data and hitting the 10,000-log cap. Example: - `GET https://<region>.swimlane.app/api/account/{account_id}/tenant/{tenant_id}/auditlogs?fromdate=2024-01-01T00:00:00Z&todate=2024-01-07T23:59:59Z` - **Leverage Pagination for Large Datasets:** When retrieving a large number of logs, utilize the pageNumber and pageSize parameters to paginate through the results efficiently. The maximum page size is 100. Example: - `GET https://<region>.swimlane.app/api/account/{account_id}/tenant/{tenant_id}/auditlogs?pageNumber=2&pageSize=50` - **Combine Filters to Optimize Performance:** Combine filters such as fromdate, todate, tenantList, and includeAccount to retrieve only the most relevant logs, reducing unnecessary data retrieval and improving performance. Example: - `GET https://<region>.swimlane.app/api/account/{account_id}/tenant/{tenant_id}/auditlogs?fromdate=2024-01-01T00:00:00Z&todate=2024-01-03T23:59:59Z&tenantList=t1,t2&includeAccount=true` - **Handle the 10,000 Log Cap:** If you expect more than 10,000 logs within a specific date range, adjust your queries to avoid hitting the cap. Split your requests into smaller batches using narrower date ranges or more specific filters. Tip: Automate requests to retrieve logs in increments, such as by day or by hour, to ensure all data is collected.