Overview
The Alerts API enables you to create, manage, and control monitoring alerts. Alerts track specific keywords, topics, or brands across various sources including social media, news, blogs, and forums.
Methods
Get Alerts
Fetch all alerts for an account.
client.get_alerts(account_id: str) -> AlertsResponse
AlertsResponse containing list of alerts
Example:
from mention import MentionClient
client = MentionClient(access_token="your-token")
alerts_response = client.get_alerts("acc_123456")
for alert in alerts_response.alerts:
print(f"{alert.name}: {alert.mentions_count} mentions")
{
"alerts": [
{
"id": "alert_123",
"name": "Brand Monitoring",
"query": {
"type": "basic",
"included_keywords": ["acme", "acme corp"],
"excluded_keywords": ["competitors"],
"required_keywords": []
},
"languages": ["en", "es"],
"countries": ["US", "GB"],
"sources": ["twitter", "news", "blog"],
"noise_detection": true,
"sentiment_analysis": true,
"mentions_count": 1523,
"unread_mentions_count": 45,
"shares_count": 3,
"followers_count": 12,
"reach": 50000,
"last_mention_at": "2024-01-20T15:30:00Z",
"created_at": "2024-01-01T10:00:00Z",
"updated_at": "2024-01-20T15:30:00Z"
}
]
}
Get Alert
Fetch a single alert by ID.
client.get_alert(account_id: str, alert_id: str) -> Alert
Alert object
Example:
alert = client.get_alert("acc_123456", "alert_123")
print(f"Alert: {alert.name}")
print(f"Keywords: {alert.query.included_keywords}")
print(f"Unread: {alert.unread_mentions_count}")
Create Alert
Create a new alert with custom query and settings.
from mention import CreateAlertRequest, AlertQuery, QueryType
client.create_alert(
account_id: str,
request: CreateAlertRequest
) -> Alert
request
CreateAlertRequest
required
Alert creation request containing name, query, and settings
Alert name (cannot be empty)
Query configuration with keywords and filters
request.languages
list[string]
default:"[\"en\"]"
List of language codes to monitor
List of country codes to filter by
request.sources
list[string]
default:"[\"web\"]"
Sources to monitor (web, twitter, facebook, news, blog, etc.)
Enable noise/spam detection
request.sentiment_analysis
Enable sentiment analysis
Alert object
Example:
from mention import MentionClient, CreateAlertRequest, AlertQuery, QueryType
client = MentionClient(access_token="your-token")
# Create query configuration
query = AlertQuery(
type=QueryType.BASIC,
included_keywords=["python SDK", "mention API"],
excluded_keywords=["spam", "irrelevant"],
required_keywords=["API"]
)
# Create alert request
request = CreateAlertRequest(
name="Python SDK Mentions",
query=query,
languages=["en"],
sources=["twitter", "reddit", "news"],
noise_detection=True,
sentiment_analysis=True
)
alert = client.create_alert("acc_123456", request)
print(f"Created alert: {alert.id}")
Update Alert
Update an existing alert’s configuration.
from mention import UpdateAlertRequest
client.update_alert(
account_id: str,
alert_id: str,
request: UpdateAlertRequest
) -> Alert
request
UpdateAlertRequest
required
Alert update request (all fields optional)
Alert object
Example:
from mention import UpdateAlertRequest, AlertQuery
# Update query with new keywords
query = AlertQuery(
included_keywords=["python", "SDK", "API client"],
excluded_keywords=["spam"]
)
request = UpdateAlertRequest(
name="Updated Alert Name",
query=query,
sources=["twitter", "reddit", "news", "blog"]
)
alert = client.update_alert("acc_123456", "alert_123", request)
print(f"Updated: {alert.name}")
Delete Alert
Delete an alert permanently.
client.delete_alert(account_id: str, alert_id: str) -> bool
True if deletion was successful
Example:
success = client.delete_alert("acc_123456", "alert_123")
if success:
print("Alert deleted")
Pause Alert
Pause an alert to temporarily stop monitoring.
client.pause_alert(account_id: str, alert_id: str) -> bool
True if pause was successful
Example:
client.pause_alert("acc_123456", "alert_123")
print("Alert paused")
Unpause Alert
Resume monitoring for a paused alert.
client.unpause_alert(account_id: str, alert_id: str) -> bool
True if unpause was successful
Example:
client.unpause_alert("acc_123456", "alert_123")
print("Alert resumed")
Models
Alert
Represents a monitoring alert.
| Field | Type | Description |
|---|
id | string | Alert ID |
name | string | Alert name |
query | AlertQuery | Query configuration |
languages | list[string] | Language codes to monitor |
countries | list[string] | Country codes to filter |
sources | list[string] | Sources being monitored |
noise_detection | boolean | Noise detection enabled |
sentiment_analysis | boolean | Sentiment analysis enabled |
mentions_count | integer | Total mentions count |
unread_mentions_count | integer | Unread mentions count |
shares_count | integer | Number of shares |
followers_count | integer | Number of followers |
reach | integer | Total reach |
last_mention_at | datetime | Last mention timestamp |
created_at | datetime | Creation timestamp |
updated_at | datetime | Last update timestamp |
AlertQuery
Query configuration for an alert.
| Field | Type | Description |
|---|
type | QueryType | Query type (basic, advanced, boolean) |
included_keywords | list[string] | Keywords to include |
excluded_keywords | list[string] | Keywords to exclude |
required_keywords | list[string] | Required keywords |
should_belong_to_owner | boolean | Filter by ownership |
QueryType
Query type enumeration:
BASIC: Simple keyword matchingADVANCED: Advanced query syntaxBOOLEAN: Boolean operators (AND, OR, NOT)