What is Streaming API?
Streaming API provides long-running connections that continuously deliver mentions as they match your filters. Unlike paginated search that returns 25 mentions per request, streaming API can deliver unlimited volumes of data through a single connection.
Why use Streaming API?
- Bulk data export - Extract large datasets efficiently without pagination
- Real-time processing - Process mentions as they arrive in your system
- Reduced API calls - One stream connection vs. hundreds of paginated requests
- Better performance - Continuous data flow without request overhead
Key Differences
Feature | Paginated Search | Export Stream |
---|---|---|
Data Volume | 25 mentions per request | Unlimited via long-running stream |
Use Case | Small datasets, exploration | Bulk data export |
Rate Limit | 30 requests/hour | 5 requests/hour, 2 concurrent |
Data Range | Recent: 7 days, Historical: unlimited | Recent: 7 days, Historical: unlimited |
Sorting | Full sorting support | Full sorting support |
Format | JSON with cursor pagination | SSE or JSON streaming |
Historical Mentions Export Stream
Follow these steps to export historical 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 historical mentions export stream
curl -N -X POST \
'https://sentione.com/api/public/v2/projects/111/mentions/search/stream' \
-H 'X-API-KEY: your_secret_key_here' \
-H 'Content-Type: application/json' \
-H 'Accept: text/event-stream' \
-d '{
"filters": {
"publishedAt": {
"from": "2025-01-01T00:00:00Z",
"to": "2025-05-22T23:59:59Z"
}
},
"sortType": "PublishedAtDescending"
}'
4. Process streaming events
The stream will return Server-Sent Events (SSE) format:
event: mention
data: {"id": "smid-wcuEd-YCoP89RC676Z97taQ2Nk97_T5HYBbFSb1rwOCzvdVLUm5GMI6tZXFUhoU5v0zQiWgt48ZllN5iXPF9tVuU4dFDR0COkaoLAVFOrYCbXju8Nztir6cPSOMdITnpMZMjNsALWcK3MU1tevSnNpZojdQD2IzBQfzYx_o", "author": {"id": "333333", "name": "Apple user", "avatar": {"url": "https://graph.facebook.com/1111111111/picture", "type": "Image"}, "gender": "Unspecified", "influenceMetrics": {}}, "source": {"socialChannel": {"id": "1111111111", "name": "Apple iPhone Fanpage Example"}, "mentionUrl": "https://www.facebook.com/1111111111/", "type": "Facebook"}, "type": "Post", "publishedAt": "2025-03-15T14:22:31.000Z", "collectedAt": "2025-03-15T14:22:36.122Z", "content": {"text": "Apple is revolutionary!", "language": {"code": "en"}, "sentiment": "Positive"}, "engagementMetrics": {"influenceScore": 8, "engagementRate": 0.125, "sourceMetrics": {"common": {"likeCount": 45, "shareCount": 12, "commentCount": 8}, "facebook": {"likeCount": 45, "loveCount": 15, "hahaCount": 2, "wowCount": 3, "sadCount": 0, "angryCount": 1}}}, "attachments": []}
id: smid-wcuEd-YCoP89RC676Z97taQ2Nk97_T5HYBbFSb1rwOCzvdVLUm5GMI6tZXFUhoU5v0zQiWgt48ZllN5iXPF9tVuU4dFDR0COkaoLAVFOrYCbXju8Nztir6cPSOMdITnpMZMjNsALWcK3MU1tevSnNpZojdQD2IzBQfzYx_o
event: heartbeat
data: {"date": "2025-05-22T10:30:00Z"}
id: 2025-05-22T10:30:00Z
event: mention
data: {"id": "smid-another-mention-id", "author": {"id": "444444", "name": "Tech Reviewer", "gender": "Male"}, "source": {"socialChannel": {"id": "2222222222", "name": "Tech Blog"}, "mentionUrl": "https://techblog.com/apple-review", "type": "Websites"}, "type": "Article", "publishedAt": "2025-03-14T09:15:22.000Z", "collectedAt": "2025-03-14T09:16:01.445Z", "content": {"text": "Apple's latest product shows mixed results in our tests.", "language": {"code": "en"}, "sentiment": "Neutral"}, "engagementMetrics": {"influenceScore": 9, "engagementRate": 0.089}, "attachments": []}
id: smid-another-mention-id
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/search/stream' \
-H 'X-API-KEY: your_secret_key_here' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"filters": {
"publishedAt": {
"from": "2025-01-01T00:00:00Z",
"to": "2025-05-22T23:59:59Z"
}
},
"sortType": "PublishedAtDescending"
}'
This returns newline-delimited JSON:
{"event": "mention", "data": {...}, "id": "mention_id"}
{"event": "heartbeat", "data": {"date": "2025-05-22T10:30:00Z"}, "id": "2025-05-22T10:30:00Z"}
{"event": "mention", "data": {...}, "id": "another_mention_id"}
Recent Mentions Export Stream
For recent mentions (last 7 days only), use the recent export stream:
curl -N -X POST \
'https://sentione.com/api/public/v2/projects/111/mentions/recent/search/stream' \
-H 'X-API-KEY: your_secret_key_here' \
-H 'Content-Type: application/json' \
-H 'Accept: text/event-stream' \
-d '{
"filters": {
"content": {
"sentiment": ["Positive", "Negative"]
},
"source": {
"type": ["Facebook", "Instagram", "X"]
}
},
"sortType": "PublishedAtDescending"
}'
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 data and lose mentions.
- Handle heartbeat events to maintain connection health
- Process events incrementally - don't wait for stream completion
- Implement reconnection logic for production use
- Monitor rate limits - only 2 concurrent stream connections allowed per account
- Choose appropriate format - SSE for real-time, JSON for batch processing
For full details on endpoints, schemas, filters, sorting options, and time ranges, refer to the OpenAPI documentation.