{"type":"api","title":"List Alerts","meta":{"id":"/apps/pubhub/media/cloud-security-apis-in-eft/83e8a10367d157243cd1c3e478b807cb81262a3d/e7c4374c-388b-3f3f-bd38-63991a559765","info":{"title":"Cisco Secure Access Alerting API","version":"1.0.0","description":"Manage the alert rules in the organization and monitor the alerts generated by the alert rules.","contact":{"name":"Cloud Security Developer Community"}},"security":[{"oauthFlow":[]}],"tags":[{"name":"Alert Rules"},{"name":"Alerts"},{"name":"Secure Access"}],"x-parser-conf":{"overview":{"markdownPath":"secure-access/reference/admin/alert-rules-overview.md","uri":"secure-access-api-reference-alerting-overview"}},"openapi":"3.0.0","servers":[{"url":"https://api.sse.cisco.com/{basePath}","variables":{"basePath":{"default":"admin/v2"}}}],"securitySchemes":{"oauthFlow":{"type":"oauth2","description":"The client credential flow.","flows":{"clientCredentials":{"tokenUrl":"https://api.sse.cisco.com/auth/v2/token","scopes":{"admin.alertrules:read":"Read Alert Rules","admin.alertrules:write":"Write Alert Rules","admin.alerts:read":"Read Alerts","admin.alerts:write":"Write Alerts"}}}}}},"spec":{"operationId":"listAlerts","summary":"List Alerts","description":"Get the properties of the alerts for the organization.","tags":["Alerts","Secure Access"],"security":[{"oauthFlow":["admin.alertrules:read"]}],"parameters":[{"name":"filters","in":"query","schema":{"type":"object","description":"The properties of the filters query parameter. Filter for the attributes of the alerts.","properties":{"status":{"type":"integer","enum":[1,2,3,4],"description":"The status of the alert. The supported status types are:\n- 1 (Active)\n- 2 (Dismissed)\n- 3 (Resolved)\n- 4 (Archived)","example":1,"$$ref":"#/components/schemas/statusAlert"},"severity":{"type":"integer","enum":[1,2,3,4],"description":"The severity of the alert. The supported severity levels are:\n- 1 (High)\n- 2 (Medium)\n- 3 (Low)\n- 4 (Info)","example":1,"$$ref":"#/components/schemas/severityAlert"},"created_after":{"description":"Filter for the alerts in the collection that the system created after the timestamp.\nProvide a date and time (ISO 8601) using the YYYY-MM-DD HH:MM:SS format.\n**Note:** You cannot use the `created_after` query parameter with the `time_range` filter.","type":"string","format":"date-time","example":"2024-01-01T00:00:00Z","$$ref":"#/components/schemas/created_after"},"modified_at":{"type":"string","format":"date-time","description":"The time and date (ISO 8601 timestamp) when the system last modified the alert.","example":"2025-01-01T00:00:00Z","$$ref":"#/components/schemas/modifiedAtAlert"},"alert_name":{"type":"string","description":"The name of the alert.","example":"Production VPN Tunnel Alert","$$ref":"#/components/schemas/nameAlert"},"pattern_search":{"description":"Provide a search pattern to query for by the alert name, alert rule name, or alert rule category name.","type":"string","example":"Network Tunnel","$$ref":"#/components/schemas/pattern_search"},"only_active_alerts_count":{"description":"Specify whether to query for the count of the active alerts only.","type":"boolean","default":false,"example":true,"$$ref":"#/components/schemas/only_active_alerts_count"},"time_range":{"type":"object","description":"The start and end times that the system uses to filter the alerts in the collection.","properties":{"start_time":{"type":"string","format":"date-time","description":"The time and date (ISO 8601 timestamp) that begins the time range. The system uses\nthe time range to filter for alerts in the collection.\nUse the 'YYYY-MM-DD HH:MM:SS' format.","example":"2024-01-01 00:00:00"},"end_time":{"type":"string","format":"date-time","description":"The time and date (ISO 8601 timestamp) that ends the time range. The system uses\nthe time range to filter for alerts in the collection.\nUse the 'YYYY-MM-DD HH:MM:SS' format.","example":"2024-12-31 23:59:59"}},"example":{"start_time":"2024-01-01 00:00:00","end_time":"2024-12-31 23:59:59"},"$$ref":"#/components/schemas/time_range"},"include_context":{"description":"Include the context field in each alert response. The context contains additional metadata about the alert.","type":"boolean","default":false,"example":true,"$$ref":"#/components/schemas/include_context"}},"$$ref":"#/components/schemas/filtersAlertObject"},"description":"Filter the alerts by one or more properties.\nSpecify the properties of the filters query parameter in the JSON format.\n\nExample:\n\n```\n{\n \"alert_name\": \"alert number 50\",\n \"created_after\": '2025-01-01T00:00:00Z'\n}\n```","$$ref":"#/components/parameters/filtersAlerts"},{"name":"limit","in":"query","required":false,"description":"The maximum number of items to return from the collection in the response.","schema":{"type":"integer","default":10},"example":5,"$$ref":"#/components/parameters/limit"},{"name":"offset","in":"query","required":false,"description":"The place to start reading in the collection. The default offset is 0.","schema":{"type":"integer","format":"int64","default":0},"example":0,"$$ref":"#/components/parameters/offset"}],"responses":{"200":{"description":"OK","headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The date and time (ISO 8601-formatted timestamp) when the system returned the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"The properties of the alerts with the alert metadata.","required":["total","severityCounts","alerts"],"properties":{"total":{"type":"integer","description":"The total number of active alerts.","example":100,"$$ref":"#/components/schemas/totalAlerts"},"severityCounts":{"description":"The number of alerts categorized by the severity.","type":"object","additionalProperties":{"type":"integer","description":"The severity and the number of alerts categorized by the severity."},"example":{"High":30,"Medium":40,"Low":20,"Info":10},"$$ref":"#/components/schemas/severityCounts"},"alerts":{"type":"array","description":"The list of the details for the alerts.","items":{"anyOf":[{"type":"object","description":"The properties of the alert.","properties":{"alertId":{"type":"string","description":"The unique identifier of the alert.","example":"AL-2048-833125-1764567890123-3f9a1c4b2d7e8f01","$$ref":"#/components/schemas/idAlert"},"organization_id":{"type":"integer","description":"The unique identifier of the organization.","example":12345,"$$ref":"#/components/schemas/organizationId"},"description":{"type":"string","description":"The description of the alert.","example":"Alert when SFO-11 Group connectivity is lost","$$ref":"#/components/schemas/descriptionAlert"},"status":{"type":"integer","enum":[1,2,3,4],"description":"The status of the alert. The supported status types are:\n- 1 (Active)\n- 2 (Dismissed)\n- 3 (Resolved)\n- 4 (Archived)","example":1,"$$ref":"#/components/schemas/statusAlert"},"rule_id":{"type":"integer","description":"The unique identifier of the associated rule.","example":42,"$$ref":"#/components/schemas/idRule"},"created_at":{"type":"string","format":"date-time","description":"The time and date (ISO 8601 timestamp) when the system created the alert.","example":"2025-01-01T00:00:00Z","$$ref":"#/components/schemas/createdAtAlert"},"modified_at":{"type":"string","format":"date-time","description":"The time and date (ISO 8601 timestamp) when the system last modified the alert.","example":"2025-01-01T00:00:00Z","$$ref":"#/components/schemas/modifiedAtAlert"},"name":{"type":"string","description":"The name of the alert.","example":"Production VPN Tunnel Alert","$$ref":"#/components/schemas/nameAlert"},"rule_type_id":{"type":"integer","description":"The identifier of the rule type.","example":1,"$$ref":"#/components/schemas/ruleTypeId"},"severity":{"type":"integer","enum":[1,2,3,4],"description":"The severity of the alert. The supported severity levels are:\n- 1 (High)\n- 2 (Medium)\n- 3 (Low)\n- 4 (Info)","example":1,"$$ref":"#/components/schemas/severityAlert"},"access_rule_context":{"type":"object","description":"The properties of the context for the changes to the access rules alerts.","properties":{"redirect_entity_url":{"type":"string","description":"The URL for the entity in Secure Access.","example":"https://dashboard.sse.cisco.com/org/8327040/secure/policy?ruleId=2312623","$$ref":"#/components/schemas/redirect_entity_url_access_rules"},"redirect_entity_url_label":{"type":"string","description":"The label for the entity's redirect URL.","example":"View entity","$$ref":"#/components/schemas/redirect_entity_url_label"},"change_type":{"type":"string","description":"The type of change made on the access rule.","enum":["create","update","delete"],"example":"update"},"changes_made":{"type":"string","description":"The description of the changes made by the system on the access rule.","example":"Rule changed"}},"$$ref":"#/components/schemas/access_rule_context"},"behavior_analytics_context":{"type":"object","description":"The properties of the context for the Behavior Analytics (UEBA) alerts.","properties":{"redirect_entity_url":{"type":"string","description":"The URL for the entity in Secure Access.","example":"https://dashboard.sse.cisco.com/org/8327040/secure/ueba/user/12345","$$ref":"#/components/schemas/redirect_entity_url_ueba"},"redirect_entity_url_label":{"type":"string","description":"The label for the entity's redirect URL.","example":"View entity","$$ref":"#/components/schemas/redirect_entity_url_label"},"redirect_event_url":{"type":"string","description":"The URL for the UEBA event in Secure Access.","example":"https://dashboard.sse.cisco.com/org/8327040/secure/ueba/event/67890"}},"$$ref":"#/components/schemas/behavior_analytics_context"}},"$$ref":"#/components/schemas/Alert"},{"type":"object","description":"The properties of the metadata for the context.\nThe system includes this field in the response when the API request sets the `include_context=true` query parameter.","example":{"redirect_entity_url":"https://dashboard.sse.cisco.com/org/8327040/secure/policy?ruleId=2313262","redirect_entity_url_label":"Test Rule","action":"create"},"$$ref":"#/components/schemas/context"}],"$$ref":"#/components/schemas/AlertWithAdditionalContext"}}},"example":{"total":100,"severityCounts":{"High":30,"Warning":50,"Low":20},"alerts":[{"alertId":"AL-2048-833125-1764567890123-3f9a1c4b2d7e8f01","organization_id":123,"description":"Alert description","status":1,"rule_id":1,"created_at":"2024-01-01T00:00:00Z","modified_at":"2024-01-01T00:00:00Z","name":"Alert Name","rule_type_id":1,"severity":1,"access_rule_context":{"redirect_entity_url":"https://dashboard.sse.cisco.com/org/8327040/secure/policy?ruleId=2313262","redirect_entity_url_label":"Test Rule","change_type":"create","changes_made":"Rule created"}}]},"$$ref":"#/components/schemas/ListAlertsResponse"},{"type":"object","description":"The total number of active alerts.\nSet `only_active_alerts_count=true` query parameter for the system to return the `total` field only.","required":["total"],"properties":{"total":{"type":"integer","description":"The total number of active alerts.","example":100,"$$ref":"#/components/schemas/totalAlerts"}},"additionalProperties":false,"$$ref":"#/components/schemas/totalCountAlertsResponse"}]},"examples":{"fullResponse":{"summary":"Full alerts response with list and counts.","value":{"total":100,"severityCounts":{"High":30,"Medium":50,"Low":20},"alerts":[{"alertId":"AL-2048-833125-1764567890123-3f9a1c4b2d7e8f01","organization_id":8327040,"description":"Access rule was modified","status":1,"rule_id":48,"created_at":"2024-01-01T00:00:00Z","modified_at":"2024-01-01T00:00:00Z","name":"Policy Change Alert","rule_type_id":10,"severity":1,"access_rule_context":{"redirect_entity_url":"https://dashboard.sse.cisco.com/org/8327040/secure/policy?ruleId=2313262","redirect_entity_url_label":"Test Rule","change_type":"create","changes_made":"Rule created"}}]},"$$ref":"#/components/examples/fullResponse"},"fullResponseWithContext":{"summary":"Full alerts response with include_context=true.","value":{"total":100,"severityCounts":{"High":30,"Medium":50,"Low":20},"alerts":[{"alertId":"AL-2048-833125-1764567890123-3f9a1c4b2d7e8f01","organization_id":8327040,"description":"Access rule was modified","status":1,"rule_id":48,"created_at":"2024-01-01T00:00:00Z","modified_at":"2024-01-01T00:00:00Z","name":"Policy Change Alert","rule_type_id":10,"severity":1,"access_rule_context":{"redirect_entity_url":"https://dashboard.sse.cisco.com/org/8327040/secure/policy?ruleId=2313262","redirect_entity_url_label":"Test Rule","change_type":"create","changes_made":"Rule created"},"context":{"redirect_entity_url":"https://dashboard.sse.cisco.com/org/8327040/secure/policy?ruleId=2313262","redirect_entity_url_label":"Test Rule","action":"create"}},{"alertId":"AL-2048-833125-1764567890124-4g0b2d5c3e8f9g02","organization_id":8327040,"description":"Anomalous user behavior detected","status":1,"rule_id":49,"created_at":"2024-01-02T10:30:00Z","modified_at":"2024-01-02T10:30:00Z","name":"UEBA Alert","rule_type_id":12,"severity":2,"behavior_analytics_context":{"redirect_entity_url":"https://dashboard.sse.cisco.com/org/8327040/secure/ueba/user/12345","redirect_entity_url_label":"View User"},"context":{"redirect_entity_url":"https://dashboard.sse.cisco.com/org/8327040/secure/ueba/user/12345","redirect_entity_url_label":"View User","action":"update"}}]},"$$ref":"#/components/examples/fullResponseWithContext"},"countOnly":{"summary":"Count-only response","value":{"total":100},"$$ref":"#/components/examples/countOnly"}}}}},"400":{"description":"Bad Request","headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The date and time (ISO 8601-formatted timestamp) when the system returned the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Bad Request","example":"Not found IAM key info for org 12355."},"status":{"type":"integer","description":"The HTTP status code returned in the response.","example":400}}}}},"$$ref":"#/components/responses/400Error"},"401":{"description":"Unauthorized","headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The date and time (ISO 8601-formatted timestamp) when the system returned the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Unauthorized","example":"Authorization token is invalid."},"status":{"type":"integer","description":"The HTTP status code returned in the response.","example":401}}}}},"$$ref":"#/components/responses/401Error"},"403":{"description":"Forbidden","headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The date and time (ISO 8601-formatted timestamp) when the system returned the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message explaining the reason for failure.","example":"Forbidden"},"status":{"type":"integer","description":"The HTTP status code returned in the response.","example":403}}}}},"$$ref":"#/components/responses/403Error"},"404":{"description":"Not Found","headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The date and time (ISO 8601-formatted timestamp) when the system returned the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message explaining the reason for failure.","example":"Not Found"},"status":{"type":"integer","description":"The HTTP status code returned in the response.","example":404}}}}},"$$ref":"#/components/responses/404Error"},"429":{"description":"Too Many Requests","headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The date and time (ISO 8601-formatted timestamp) when the system returned the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message explaining the reason for failure.","example":"Rate limit exceeded"},"status":{"type":"integer","description":"The HTTP status code returned in the response.","example":404}}}}},"$$ref":"#/components/responses/429Error"},"500":{"description":"Internal Server Error","headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The date and time (ISO 8601-formatted timestamp) when the system returned the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message explaining the reason for failure.","example":"Internal Server Error"},"status":{"type":"integer","description":"The HTTP status code returned in the response.","example":500}}}}},"$$ref":"#/components/responses/500Error"}},"__originalOperationId":"listAlerts","method":"get","path":"/alerting/alerts"}}