Audit Logging

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 //\<region> 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 //\<region> swimlane app/api/account/{account id}/tenant/{tenant id}/logs 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 //\&lt;region\&gt; swimlane app/api/public/audit/account/{account id}/tenant/{tenant id}/auditlogs?pagenumber=2\&pagesize=50 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 //\<region> 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) log in to swimlane click on your profile & user settings in the top right corner navigate to personal access token click generate new token 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 curl x get "https //\<region> swimlane app/api/public/audit/account/{account id}/auditlogs" \ h "private token \<your personal access token>" replace \<region> with your swimlane instance’s region replace {account id} with your account’s id replace \<your personal access token> 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 { "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 { "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 { "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 { "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 { "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 { "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 { "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 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 { "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 { "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 { "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 { "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 { "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" } 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 //\&lt;region\&gt; 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 //\&lt;region\&gt; 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 //\&lt;region\&gt; 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