Watch for new mentions in project using live-stream

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.