GET Alerts API Developer Guide

Applies to: Listening Alerts API (GET /api/v3/listening/alert)

1. Overview

Use the GET Alerts API to retrieve the configuration and details of existing Listening Alerts, including alert metadata, filter configurations, notification recipients, distribution settings, and alert-specific conditions.

You can retrieve alerts by:

Providing a single alert ID.
Providing multiple alert IDs as a comma-separated list.
Specifying a module name.

The API supports partial-success responses. When a request contains valid and invalid identifiers, successfully retrieved alerts are returned in data, while identifier-specific failures are returned in errors.

2. Base URL and Endpoint

https://api3.sprinklr.com/{env}/api/v3/listening/alert

Attribute	Value
HTTP method	`GET`
Resource path	`/api/v3/listening/alert`
Response format	JSON
Authentication	OAuth 2.0 bearer token and API key

3. Authentication and Common Headers

Header	Required	Type	Value	Description
`Accept`	Yes	String	`application/json`	Specifies the expected response media type.
`Authorization`	Yes	String	`Bearer {accessToken}`	OAuth 2.0 bearer token used to authenticate the request.
`Key`	Yes	String	`{apiKey}`	API key used to authorize the client application.
`Cookie`	No	String	`JSESSIONID={sessionId}`	Session identifier used for browser-based authenticated sessions. Generally unnecessary for OAuth-based integrations.

Security note: Do not publish real access tokens, API keys, or session IDs in API documentation. Use placeholders in all examples.

4. Query Parameters

Parameter	Required	Type	Description
`id`	Conditional	String or comma-separated string	Unique identifier of a Listening Alert. Provide multiple IDs as a comma-separated list.
`module`	Conditional	String	Module whose alerts should be retrieved. Use instead of `id`.

Either id or module must be provided.

5. Retrieve an Alert by a Single ID

Retrieves the complete configuration of one Listening Alert.

Example Request

curl --location --globoff '{{baseUrl}}/api/v3/listening/alert?id=6995ba46d7890350f0e0ce12' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Key: {{apiKey}}'

Request Parameters

Parameter	Sub-Parameter	In	Required	Type	Description
`id`	N/A	Query	Yes	String	Unique identifier of the Listening Alert to retrieve.
`Accept`	N/A	Header	Yes	String	Expected response type. Supported value: `application/json`.
`Authorization`	`accessToken`	Header	Yes	String	OAuth access token prefixed with `Bearer`.
`Key`	`apiKey`	Header	Yes	String	API key associated with the client application.

Example Response

{
  "data": [
    {
      "id": "6995ba46d7890350f0e0ce12",
      "name": "Test-Alert-Fetch-API",
      "description": "Test-Alert-Fetch-API desc",
      "category": "SMART_ALERT",
      "module": "LISTENING",
      "status": "SUCCESS",
      "filterDimensions": [
        {
          "dimensionName": "QUERY",
          "filterType": "IN",
          "values": ["india"],
          "details": {
            "contentType": "DB_FILTER",
            "DB_FILTER_REPORT_NAME": "SPRINKSIGHTS",
            "OLD_DIM_NAME": "TOPIC_QUERY",
            "INPUT_TYPE": "FREE_TEXT",
            "EXCLUDE_IN_THEME_PREVIEW": "true",
            "displayNameForWarning": "Keyword Query",
            "EXIST_FILTER": false,
            "singleSelect": "true",
            "uniqueId": "D_QUERY"
          }
        }
      ],
      "tags": [],
      "enabled": true,
      "distributionConfig": {
        "userIds": [66006626, 66062939, 66007863],
        "userGroupIds": [],
        "emailIds": [],
        "sendEmailNotification": true,
        "customEmailSubject": "Listening Alert Test "
      },
      "smartAlertConfig": {
        "smartAlertMetrics": ["NEGATIVE_SENTIMENT"],
        "suddenAnomalyEnabled": true,
        "longTermTrendsEnabled": false
      },
      "createdTime": 1771420230634,
      "modifiedTime": 1782478947322,
      "ownerUserId": 66006626,
      "lastModifiedUserId": 0,
      "clientId": 66000002
    }
  ],
  "errors": []
}

6. Retrieve Multiple Alerts by ID

Retrieves multiple Listening Alerts by supplying a comma-separated list of IDs.

Example Request

curl --location --globoff '{{baseUrl}}/api/v3/listening/alert?id=6995ba46d7890350f0e0ce12%2C699588f0bc163922661c691d' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Key: {{apiKey}}'

Request Parameters

Parameter	Sub-Parameter	In	Required	Type	Description
`id`	N/A	Query	Yes	String	Comma-separated list of Listening Alert IDs. `%2C` is the URL-encoded comma.
`Accept`	N/A	Header	Yes	String	Expected response type. Supported value: `application/json`.
`Authorization`	`accessToken`	Header	Yes	String	OAuth access token prefixed with `Bearer`.
`Key`	`apiKey`	Header	Yes	String	API key associated with the client application.

Example Response

{
  "data": [
    {
      "id": "6995ba46d7890350f0e0ce12",
      "name": "Test-Alert-Fetch-API",
      "description": "Test-Alert-Fetch-API desc",
      "category": "SMART_ALERT",
      "module": "LISTENING",
      "status": "IN_PROGRESS",
      "filterDimensions": [
        {
          "dimensionName": "QUERY",
          "filterType": "IN",
          "values": ["india"],
          "details": {
            "contentType": "DB_FILTER",
            "DB_FILTER_REPORT_NAME": "SPRINKSIGHTS",
            "OLD_DIM_NAME": "TOPIC_QUERY",
            "INPUT_TYPE": "FREE_TEXT",
            "EXCLUDE_IN_THEME_PREVIEW": "true",
            "displayNameForWarning": "Keyword Query",
            "EXIST_FILTER": false,
            "singleSelect": "true",
            "uniqueId": "D_QUERY"
          }
        }
      ],
      "tags": [],
      "enabled": true,
      "distributionConfig": {
        "userIds": [66006626, 66062939, 66007863],
        "userGroupIds": [],
        "emailIds": [],
        "sendEmailNotification": true,
        "customEmailSubject": "Listening Alert Test "
      },
      "smartAlertConfig": {
        "smartAlertMetrics": ["NEGATIVE_SENTIMENT"],
        "suddenAnomalyEnabled": true,
        "longTermTrendsEnabled": true
      },
      "createdTime": 1771420230634,
      "modifiedTime": 1771420279441,
      "ownerUserId": 66006626,
      "lastModifiedUserId": -100,
      "clientId": 66000002
    },
    {
      "id": "699588f0bc163922661c691d",
      "name": "AlertManagerStatic_011771407491199",
      "description": "Alert Created Via Automation",
      "category": "STATIC_ALERT",
      "module": "LISTENING",
      "status": "SUCCESS",
      "filterDimensions": [
        {
          "dimensionName": "TOPIC_IDS",
          "filterType": "IN",
          "values": ["692feaaab7d0a90babc9f775"],
          "details": {
            "displayNameForWarning": "Topic",
            "USE_SNAPSHOT_VALUE": false,
            "type": "DIMENSION",
            "dF": true,
            "OLD_DIM_NAME": "TOPIC",
            "nameQueryLookupSupported": "true",
            "DRILLDOWN": false,
            "EXIST_FILTER": false,
            "reportName": "SPRINKSIGHTS",
            "reports": ["SPRINKSIGHTS"]
          }
        }
      ],
      "tags": ["testtags"],
      "enabled": true,
      "distributionConfig": {
        "userIds": [],
        "userGroupIds": [],
        "emailIds": ["autouser1@sprinklr.com"],
        "sendEmailNotification": true,
        "customEmailSubject": "Automation Alert",
        "senderAlias": "autouser2@sprinklr.com"
      },
      "volumetricAlertConfig": {
        "alertTriggerConditionType": "ALERT_TRIGGER_TYPE_THRESHOLD",
        "conditions": [
          {
            "dimensionName": "STATIC_ALERT_MENTIONS_VOLUME",
            "filterType": "GT",
            "values": [100],
            "details": {
              "displayNameForWarning": "Volume of Mentions",
              "USE_SNAPSHOT_VALUE": false,
              "type": "DIMENSION",
              "ALLOWED_FILTER_TYPES": ["GT"],
              "MEASUREMENT_NAME": "MENTIONS_COUNT",
              "STATIC_ALERT_TYPE": "STATIC_ALERT_MENTIONS_VOLUME",
              "INPUT_TYPE": "NUMERIC",
              "reportName": "SPRINKSIGHTS",
              "reports": ["SPRINKSIGHTS"],
              "MEASUREMENT_AGG_TYPE": "SUM"
            }
          }
        ]
      },
      "createdTime": 1771407600013,
      "modifiedTime": 1771408982373,
      "ownerUserId": 66070831,
      "lastModifiedUserId": -100,
      "clientId": 66000002
    }
  ],
  "errors": []
}

7. Retrieve Multiple Alerts with Partial Success

Retrieves available alerts while returning identifier-specific errors for empty, malformed, inaccessible, or non-existent values.

Example Request

curl --location --globoff '{{baseUrl}}/api/v3/listening/alert?id=6995ba46d7890350f0e0ce12%2C699588f0bc163922661c691d%2C%2Cinvalid%2Ctest' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Key: {{apiKey}}'

Example Partial-Success Error Fragment

{
  "data": [
    {
      "id": "6995ba46d7890350f0e0ce12",
      "category": "SMART_ALERT"
    },
    {
      "id": "699588f0bc163922661c691d",
      "category": "STATIC_ALERT"
    }
  ],
  "errors": [
    {
      "id": "6995baaef58d8b601be9edb2",
      "code": 400,
      "message": "Invalid id format: ''. Value cannot be empty or blank."
    },
    {
      "id": "6995baaef58d8b601be9edb3",
      "code": 404,
      "message": "Alert not found for id: 'invalid'. Verify the alert exists and you have access permissions."
    },
    {
      "id": "6995baaef58d8b601be9edb4",
      "code": 404,
      "message": "Alert not found for id: 'test'. Verify the alert exists and you have access permissions."
    }
  ]
}

A partial-success response can contain both populated data and errors arrays.

8. Response Parameters

Parameter	Sub-Parameter	Type	Description
`data`	N/A	Array	Listening Alerts successfully returned by the API.
`data[]`	`id`	String	Unique identifier of the alert.
`data[]`	`name`	String	Name of the alert.
`data[]`	`description`	String	Description of the alert.
`data[]`	`category`	String	Alert category, such as `SMART_ALERT` or `STATIC_ALERT`.
`data[]`	`module`	String	Module associated with the alert, such as `LISTENING`.
`data[]`	`status`	String	Current processing status, such as `IN_PROGRESS` or `SUCCESS`.
`data[]`	`filterDimensions`	Array	Filters that define the alert criteria.
`data[]`	`tags`	Array	Tags associated with the alert.
`data[]`	`enabled`	Boolean	Indicates whether the alert is enabled.
`data[]`	`distributionConfig`	Object	Alert recipient and notification configuration.
`data[]`	`smartAlertConfig`	Object	Smart Alert configuration. Returned for Smart Alerts.
`data[]`	`volumetricAlertConfig`	Object	Static or volumetric alert configuration. Returned for applicable alerts.
`data[]`	`createdTime`	Long	Alert creation time in epoch milliseconds.
`data[]`	`modifiedTime`	Long	Alert modification time in epoch milliseconds.
`data[]`	`ownerUserId`	Long	User ID of the alert owner.
`data[]`	`lastModifiedUserId`	Long	User ID of the last modifier. System-generated updates can use a system identifier.
`data[]`	`clientId`	Long	Identifier of the client account or workspace.
`errors`	N/A	Array	Request-item errors. Empty when no item-level errors occur.

8.1 Filter Dimensions

Parameter	Sub-Parameter	Type	Description
`filterDimensions[]`	`dimensionName`	String	Name of the filter dimension.
`filterDimensions[]`	`filterType`	String	Filter operation applied to the dimension.
`filterDimensions[]`	`values`	Array	Values used by the filter.
`filterDimensions[]`	`details`	Object	Additional filter metadata.

8.2 Filter Dimension Details

Parameter	Type	Description
`contentType`	String	Filter content type.
`DB_FILTER_REPORT_NAME`	String	Report associated with the database filter.
`OLD_DIM_NAME`	String	Legacy dimension name.
`INPUT_TYPE`	String	Input type supported by the filter.
`EXCLUDE_IN_THEME_PREVIEW`	String	Indicates whether the filter is excluded from theme preview.
`displayNameForWarning`	String	Display label used in warnings.
`EXIST_FILTER`	Boolean	Indicates whether the filter is an existence filter.
`singleSelect`	String	Indicates whether only one value can be selected.
`uniqueId`	String	Unique identifier of the dimension configuration.
`USE_SNAPSHOT_VALUE`	Boolean	Indicates whether a snapshot value is used.
`type`	String	Dimension configuration type.
`dF`	Boolean	Internal dimension flag returned by the API.
`nameQueryLookupSupported`	String	Indicates whether name-based lookup is supported.
`DRILLDOWN`	Boolean	Indicates whether drill-down is supported.
`reportName`	String	Associated report name.
`reports`	Array	Associated reports.

8.3 Distribution Configuration

Parameter	Type	Description
`userIds`	Array	User IDs configured to receive alert notifications.
`userGroupIds`	Array	User group IDs configured to receive notifications.
`emailIds`	Array	Email addresses configured as recipients.
`sendEmailNotification`	Boolean	Indicates whether email notifications are enabled.
`customEmailSubject`	String	Custom subject line for alert emails.
`senderAlias`	String	Sender email alias used for notifications.

8.4 Smart Alert Configuration

Parameter	Type	Description
`smartAlertMetrics`	Array	Metrics monitored by the Smart Alert.
`suddenAnomalyEnabled`	Boolean	Indicates whether sudden-anomaly detection is enabled.
`longTermTrendsEnabled`	Boolean	Indicates whether long-term trend analysis is enabled.

8.5 Volumetric Alert Configuration

Parameter	Type	Description
`alertTriggerConditionType`	String	Trigger condition type used by the alert.
`conditions`	Array	Conditions evaluated against the configured threshold.

8.6 Volumetric Condition

Parameter	Type	Description
`dimensionName`	String	Metric or dimension monitored by the condition.
`filterType`	String	Comparison operator used to evaluate the condition.
`values`	Array	Threshold values used to trigger the alert.
`details`	Object	Additional condition metadata.

8.7 Volumetric Condition Details

Parameter	Type	Description
`displayNameForWarning`	String	User-friendly metric label.
`USE_SNAPSHOT_VALUE`	Boolean	Indicates whether a snapshot value is used.
`type`	String	Condition dimension type.
`ALLOWED_FILTER_TYPES`	Array	Supported filter operators.
`MEASUREMENT_NAME`	String	Measurement tracked by the condition.
`STATIC_ALERT_TYPE`	String	Static alert metric type.
`INPUT_TYPE`	String	Input type supported by the metric.
`reportName`	String	Associated report name.
`reports`	Array	Associated reports.
`MEASUREMENT_AGG_TYPE`	String	Aggregation method applied to the metric.

8.8 Error Object

Parameter	Type	Description
`id`	String	Unique identifier associated with the error record.
`code`	Integer	HTTP-style error code for the failed item.
`message`	String	Description of the validation or retrieval failure.

9. Response Codes

HTTP Code	Description
`200 OK`	Alerts returned successfully. The body can also contain item-level errors for a partial-success request.
`400 Bad Request`	One or more request parameters are invalid, empty, or malformed.
`401 Unauthorized`	Authentication failed.
`403 Forbidden`	The authenticated user does not have sufficient permission.
`404 Not Found`	A requested alert cannot be found or accessed.

10. Use Cases

10.1 Retrieve a Specific Alert

Provide a single alert ID to retrieve its complete configuration.

10.2 Retrieve Multiple Alerts

Supply multiple alert IDs as a comma-separated list to fetch several alert definitions in one request.

10.3 Retrieve Alerts by Module

Provide the module parameter to retrieve alerts associated with a module.

10.4 Review Distribution Configuration

Inspect recipients, sender configuration, and email settings before updating alert delivery.

10.5 Audit Alert Conditions

Review Smart Alert and Volumetric Alert conditions to validate anomaly-detection settings and configured thresholds.

All IDs, email addresses, timestamps, and configuration values in this guide are sample values for documentation purposes.

GET Alerts API Developer Guide

1. Overview

2. Base URL and Endpoint

3. Authentication and Common Headers

4. Query Parameters

5. Retrieve an Alert by a Single ID

Example Request

Request Parameters

Example Response

6. Retrieve Multiple Alerts by ID

Example Request

Request Parameters

Example Response

7. Retrieve Multiple Alerts with Partial Success

Example Request

Example Partial-Success Error Fragment

8. Response Parameters

8.1 Filter Dimensions

8.2 Filter Dimension Details

8.3 Distribution Configuration

8.4 Smart Alert Configuration

8.5 Volumetric Alert Configuration

8.6 Volumetric Condition

8.7 Volumetric Condition Details

8.8 Error Object

9. Response Codes

10. Use Cases

10.1 Retrieve a Specific Alert

10.2 Retrieve Multiple Alerts

10.3 Retrieve Alerts by Module

10.4 Review Distribution Configuration

10.5 Audit Alert Conditions

Was this helpful?