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

FeatureExport StreamLive Stream
Data TypeHistorical data exportReal-time mentions as collected
Use CaseBulk data exportReal-time monitoring
Rate Limit5 requests/hour, 2 concurrent5 requests/hour, 2 concurrent
Data RangeRecent: 7 days, Historical: unlimitedLast 7 days only
SortingFull sorting supportNo sorting (random order)
FormatSSE or JSON streamingSSE or JSON streaming
BackfillNot supportedOptional 0-5 minutes
DurationFinite (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

  1. 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.
  2. Handle random order - Mentions arrive in random order due to different collection delays. Don't assume chronological order.
  3. Handle heartbeat events to maintain connection health
  4. Implement reconnection logic for production use - Live streams should reconnect automatically if connection drops
  5. Monitor rate limits - Only 2 concurrent stream connections allowed per account
  6. 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.
  7. Design for infinite streams - Live streams run indefinitely, design your processing accordingly
  8. 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.