What is Live Streaming API?
Live Streaming API provides real-time connections that continuously deliver mentions as they are collected by SentiOne system. Unlike export streams that deliver historical data, live streaming delivers mentions as they get collected by Listen platform with optional backfill of recent data.
Why use Live Streaming API?
- Real-time monitoring - Get mentions immediately as they're collected
- Crisis management - Detect and respond to issues as they emerge
- Live sentiment tracking - Monitor brand perception in real-time
- Event monitoring - Track mentions during live events, campaigns, or product launches
- Competitive intelligence - Stay ahead with instant competitor mention alerts
Key Differences
Feature | Export Stream | Live Stream |
---|---|---|
Data Type | Historical data export | Real-time mentions as collected |
Use Case | Bulk data export | Real-time monitoring |
Rate Limit | 5 requests/hour, 2 concurrent | 5 requests/hour, 2 concurrent |
Data Range | Recent: 7 days, Historical: unlimited | Last 7 days only |
Sorting | Full sorting support | No sorting (random order) |
Format | SSE or JSON streaming | SSE or JSON streaming |
Backfill | Not supported | Optional 0-5 minutes |
Duration | Finite (ends when data exhausted) | Infinite (continuous) |
Live Mentions Stream
Follow these steps to monitor live mentions from Listen project using streaming API:
1. List Projects
curl -X GET \
'https://sentione.com/api/public/v2/projects' \
-H 'X-API-KEY: your_secret_key_here'
2. Extract project ID from the response
{
"data": [
{ "id": 111, "name": "Apple" },
{ "id": 222, "name": "Android" }
],
"cursor": "abc123"
}
Select desired project id
(eg. 111 for Apple project)
3. Start live mentions stream
curl -N -X POST \
'https://sentione.com/api/public/v2/projects/111/mentions/recent/search/stream/live?backfillMinutes=5' \
-H 'X-API-KEY: your_secret_key_here' \
-H 'Content-Type: application/json' \
-H 'Accept: text/event-stream' \
-d '{
"filters": {
"type": ["Post", "Comment"],
"source": {
"type": ["X", "Reddit", "Facebook"]
},
"content": {
"sentiment": ["Negative"]
}
}
}'
4. Process live streaming events
The stream will return Server-Sent Events (SSE) format with mentions arriving in random order:
event: mention
data: {"id": "smid-live-mention-1", "author": {"id": "555555", "name": "Live User", "gender": "Female"}, "source": {"socialChannel": {"id": "3333333333", "name": "Tech Discussion Forum"}, "mentionUrl": "https://reddit.com/r/technology/comments/abc123", "type": "Reddit"}, "type": "Comment", "publishedAt": "2025-05-22T14:25:10.000Z", "collectedAt": "2025-05-22T14:25:15.445Z", "content": {"text": "Apple's latest update is causing issues with my device. Very frustrated!", "language": {"code": "en"}, "sentiment": "Negative"}, "engagementMetrics": {"influenceScore": 6, "engagementRate": 0.045, "sourceMetrics": {"common": {"likeCount": 2, "commentCount": 1}}}, "attachments": []}
id: smid-live-mention-1
event: heartbeat
data: {"date": "2025-05-22T14:25:30Z"}
id: 2025-05-22T14:25:30Z
event: mention
data: {"id": "smid-live-mention-2", "author": {"id": "666666", "name": "TechReporter", "gender": "Male"}, "source": {"socialChannel": {"id": "4444444444", "name": "Breaking Tech News"}, "mentionUrl": "https://twitter.com/TechReporter/status/1234567890", "type": "X"}, "type": "Post", "publishedAt": "2025-05-22T14:23:45.000Z", "collectedAt": "2025-05-22T14:25:20.123Z", "content": {"text": "BREAKING: Apple faces criticism over recent policy changes", "language": {"code": "en"}, "sentiment": "Negative"}, "engagementMetrics": {"influenceScore": 9, "engagementRate": 0.234, "sourceMetrics": {"common": {"likeCount": 156, "shareCount": 89, "commentCount": 45}, "twitter": {"retweetsCount": 89, "favouritesCount": 156}}}, "attachments": []}
id: smid-live-mention-2
5. Alternative: JSON streaming format
For JSON lines format instead of SSE:
curl -N -X POST \
'https://sentione.com/api/public/v2/projects/111/mentions/recent/search/stream/live?backfillMinutes=3' \
-H 'X-API-KEY: your_secret_key_here' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"filters": {
"source": {
"type": ["X", "Facebook"]
}
}
}'
This returns newline-delimited JSON:
{"event": "mention", "data": {...}, "id": "live_mention_id"}
{"event": "heartbeat", "data": {"date": "2025-05-22T14:26:00Z"}, "id": "2025-05-22T14:26:00Z"}
{"event": "mention", "data": {...}, "id": "another_live_mention_id"}
Live Stream Processing Tips
- Use non-blocking event processing - Process events asynchronously to avoid blocking the stream. If your processing logic is slow, you may not keep up with incoming live data and lose mentions.
- Handle random order - Mentions arrive in random order due to different collection delays. Don't assume chronological order.
- Handle heartbeat events to maintain connection health
- Implement reconnection logic for production use - Live streams should reconnect automatically if connection drops
- Monitor rate limits - Only 2 concurrent stream connections allowed per account
- Choose appropriate backfill - By default, you only get mentions collected from the moment the stream connection starts. With backfill (0-5 minutes), you can receive mentions collected up to 5 minutes before stream start. Useful when you lose connection and need to catch up.
- Design for infinite streams - Live streams run indefinitely, design your processing accordingly
- Buffer critical events - For important mentions (e.g., crisis situations), implement local buffering
Use Case Examples
Crisis Management
Monitor negative sentiment in real-time to detect potential issues:
curl -N -X POST \
'https://sentione.com/api/public/v2/projects/111/mentions/recent/search/stream/live' \
-H 'X-API-KEY: your_secret_key_here' \
-H 'Content-Type: application/json' \
-H 'Accept: text/event-stream' \
-d '{
"filters": {
"content": {
"sentiment": ["Negative"]
}
}
}'
Event Monitoring
Track mentions during live events or product launches:
curl -N -X POST \
'https://sentione.com/api/public/v2/projects/111/mentions/recent/search/stream/live?backfillMinutes=5' \
-H 'X-API-KEY: your_secret_key_here' \
-H 'Content-Type: application/json' \
-H 'Accept: text/event-stream' \
-d '{
"filters": {
"type": ["Post"],
"source": {
"type": ["X", "Instagram", "Facebook"]
}
}
}'
Social Media Monitoring
Monitor specific social platforms for immediate responses:
curl -N -X POST \
'https://sentione.com/api/public/v2/projects/111/mentions/recent/search/stream/live' \
-H 'X-API-KEY: your_secret_key_here' \
-H 'Content-Type: application/json' \
-H 'Accept: text/event-stream' \
-d '{
"filters": {
"source": {
"type": ["X"]
},
"type": ["Post", "Comment"]
}
}'
For full details on endpoints, schemas, filters, and parameters, refer to the OpenAPI documentation.