---
updatedAt: 2026-04-21T02:50:19.000Z
agentTools:
  projectIndex: https://listen.help.sentione.com/llms.txt
---

# Project's recent mentions live stream

**Tier**: Enterprise

**Rate limit**: 14400 requests per hour, 2 concurrent connections

**Data limitations:** 

* Mentions cap - monthly limit applies
* Mentions published within last 7 days, collected by the system since the connection start (with optional 5-minute backfill)

**⚠️ WARNING**: Due to limitations of readme.com API console, the **Try it out** button will not work for streaming endpoints. Please copy the generated curl command and execute it in your terminal to test streaming functionality.

**⚠️ WARNING**: The order of mentions in the **live stream** is random and you cannot make any assumptions about it. Due to the nature of the **live-stream** and different delays of particular mentions, they may arrive out of chronological order.

**Infinite live-stream** of mentions published within **last 7 days** which are being collected by SentiOne system from the moment the stream connection starts.

Supports optional backfill of recent mentions and filtering.
Supports both **SSE** (Server-Sent Events) and **NDJSON** (Newline Delimited JSON) formats.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Listen API Reference (V2)",
    "version": "2.0.10",
    "description": "**Rate limiting:**\n  • Projects list: 300 requests per hour\n  • Search endpoints (full search & recent search): 30 requests per hour (shared)\n  • Stream endpoints (export streams & live streams): 14400 requests per hour, 2 concurrent connections\n\n**Rate limiting headers:**\nAll API responses include the following headers:\n  • `x-rate-limit-limit`: Limit of requests for particular API endpoint\n  • `x-rate-limit-reset`: Unix timestamp (seconds) when limits will reset\n  • `x-rate-limit-remaining`: Remaining number of requests\n"
  },
  "servers": [
    {
      "url": "https://sentione.com/api/public/v2"
    },
    {
      "url": "https://{hostname}/api/public/v2",
      "variables": {
        "hostname": {
          "default": "sentione.com"
        }
      }
    },
    {
      "url": "{server}/api/public/v2",
      "variables": {
        "server": {
          "default": "https://sentione.com"
        }
      }
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY",
        "description": "Your API key for authenticating requests. \nObtain or regenerate your key at https://sentione.com/app#/organization/api\n"
      }
    },
    "schemas": {
      "LiveStreamFilters": {
        "type": "object",
        "description": "Filters to apply to live stream searches.\nIf omitted in Recent mentions search, `publishedAt` defaults to the last 7 days.\n",
        "properties": {
          "publishedAt": {
            "$ref": "#/components/schemas/TimeRange",
            "description": "Time range for filtering by published date (ISO 8601 UTC format, e.g. 2025-05-22T10:30:00Z).\nDefaults to last 7 days in Recent mentions search.\n"
          },
          "source": {
            "$ref": "#/components/schemas/SourceFilters",
            "description": "Criteria to filter mentions by their source"
          },
          "type": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MentionType"
            },
            "description": "List of mention types to include (e.g., Post, Comment)"
          },
          "content": {
            "$ref": "#/components/schemas/MentionContentFilters",
            "description": "Filters related to the content of mentions (e.g., sentiment)"
          },
          "location": {
            "$ref": "#/components/schemas/LocationFilters",
            "description": "Filters related to the location of mentions (e.g. fr, pl)"
          }
        }
      },
      "TimeRange": {
        "type": "object",
        "description": "Range of dates to filter mentions by, specified in ISO 8601 format and UTC timezone (e.g. 2025-05-22T10:30:00Z).\n",
        "properties": {
          "from": {
            "type": "string",
            "format": "date-time",
            "description": "Start datetime of the range (inclusive) - ISO8601 format (e.g. 2025-05-20T00:00:00Z)"
          },
          "to": {
            "type": "string",
            "format": "date-time",
            "description": "End datetime of the range (exclusive) - ISO8601 format (e.g. 2025-05-22T23:59:59Z)"
          }
        }
      },
      "MentionContentFilters": {
        "type": "object",
        "description": "Filters specific to the content attributes of mentions",
        "properties": {
          "sentiment": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Sentiment"
            },
            "description": "List of sentiments to include (e.g. Positive, Negative)"
          },
          "query": {
            "type": "string",
            "description": "Listen Query Language query to match against mention content.\nSee full specification: https://listen.help.sentione.com/update/reference/listen-query-language\nMaximum length of the query is 500 characters.\n",
            "maxLength": 500,
            "example": "\"great product\" AND phone* NOT (fake OR refurbished)"
          },
          "language": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LanguageCode"
            },
            "description": "List of language codes (ISO 639-1) to include (e.g. en, es)"
          }
        }
      },
      "LanguageCode": {
        "type": "string",
        "description": "ISO 639-1 language code"
      },
      "LocationFilters": {
        "type": "object",
        "description": "Filters for the geographical location details of the mentions",
        "properties": {
          "type": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CountryCode"
            },
            "nullable": true,
            "description": "List of country codes (ISO 3166) to include (e.g. en, fr)"
          }
        }
      },
      "CountryCode": {
        "type": "string",
        "description": "ISO 3166 country code"
      },
      "MentionType": {
        "type": "string",
        "description": "Enumeration of possible mention formats",
        "enum": [
          "Post",
          "Comment",
          "Article",
          "PrivateMessage",
          "Share"
        ]
      },
      "SourceType": {
        "type": "string",
        "description": "Enumeration of platforms or channels where mentions originate",
        "enum": [
          "Facebook",
          "Websites",
          "Instagram",
          "Forums",
          "X",
          "Blogs",
          "TikTok",
          "Reviews",
          "Reddit",
          "Video",
          "Imported",
          "Other"
        ]
      },
      "SourceFilters": {
        "type": "object",
        "description": "Criteria to filter mentions by their source",
        "properties": {
          "type": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SourceType"
            },
            "description": "List of source types to include (e.g., Facebook, X)"
          }
        }
      },
      "Sentiment": {
        "type": "string",
        "description": "Sentiment classification of mention content",
        "enum": [
          "Positive",
          "Negative",
          "Neutral",
          "Unspecified"
        ]
      },
      "Language": {
        "type": "object",
        "description": "Language details",
        "properties": {
          "code": {
            "type": "string",
            "description": "ISO 639-1 language code"
          }
        },
        "required": [
          "code"
        ]
      },
      "MentionContent": {
        "type": "object",
        "description": "Detailed content of the mention",
        "properties": {
          "title": {
            "type": "string",
            "nullable": true,
            "description": "Title of the mention. For example: article title on a news portal or YouTube video name. (Optional)"
          },
          "text": {
            "type": "string",
            "nullable": true,
            "description": "Text body of the mention. (Optional)"
          },
          "review": {
            "$ref": "#/components/schemas/Review",
            "nullable": true,
            "description": "Author's review (if any) attached to mention. Available only for\nsources such as Google Reviews and other similar sources. Absent\nfor non-review sources.\n"
          },
          "language": {
            "$ref": "#/components/schemas/Language",
            "nullable": true,
            "description": "Language of the mention content"
          },
          "sentiment": {
            "$ref": "#/components/schemas/Sentiment",
            "description": "Sentiment classification of the mention"
          }
        },
        "required": [
          "sentiment"
        ]
      },
      "EngagementMetrics": {
        "type": "object",
        "description": "Summary of overall and per-source engagement metrics",
        "properties": {
          "influenceScore": {
            "type": "integer",
            "nullable": true,
            "description": "Influence score (1 - 10)"
          },
          "engagementRate": {
            "type": "number",
            "format": "double",
            "nullable": true,
            "description": "Rate of engagement relative to exposure"
          },
          "sourceMetrics": {
            "$ref": "#/components/schemas/SourceEngagementMetrics",
            "description": "Source-specific breakdown of engagement metrics"
          }
        },
        "required": [
          "sourceMetrics"
        ]
      },
      "SourceEngagementMetrics": {
        "type": "object",
        "description": "Engagement metrics broken down by individual sources",
        "properties": {
          "common": {
            "$ref": "#/components/schemas/GenericSourceEngagementMetrics",
            "description": "Common engagement metrics across all sources"
          },
          "facebook": {
            "$ref": "#/components/schemas/FacebookSourceEngagementMetrics",
            "nullable": true,
            "description": "Facebook-specific reaction counts"
          },
          "newsAggregators": {
            "$ref": "#/components/schemas/NewsAggregatorSourceEngagementMetrics",
            "nullable": true,
            "description": "Counts of interactions on news aggregator platforms"
          },
          "twitter": {
            "$ref": "#/components/schemas/TwitterSourceEngagementMetrics",
            "nullable": true,
            "description": "Twitter-specific engagement counts"
          }
        },
        "required": [
          "common"
        ]
      },
      "GenericSourceEngagementMetrics": {
        "type": "object",
        "description": "Common engagement metrics for a mention",
        "properties": {
          "likeCount": {
            "type": "integer",
            "format": "int64",
            "nullable": true,
            "description": "Number of likes; optional"
          },
          "shareCount": {
            "type": "integer",
            "format": "int64",
            "nullable": true,
            "description": "Number of shares; optional"
          },
          "commentCount": {
            "type": "integer",
            "format": "int64",
            "nullable": true,
            "description": "Number of comments; optional"
          },
          "viewCount": {
            "type": "integer",
            "format": "int64",
            "nullable": true,
            "description": "Number of views; optional"
          }
        }
      },
      "FacebookSourceEngagementMetrics": {
        "type": "object",
        "description": "Reaction counts specific to Facebook",
        "properties": {
          "likeCount": {
            "type": "integer",
            "format": "int64",
            "description": "Number of likes"
          },
          "loveCount": {
            "type": "integer",
            "format": "int64",
            "description": "Number of 'Love' reactions"
          },
          "hahaCount": {
            "type": "integer",
            "format": "int64",
            "description": "Number of 'Haha' reactions"
          },
          "wowCount": {
            "type": "integer",
            "format": "int64",
            "description": "Number of 'Wow' reactions"
          },
          "sadCount": {
            "type": "integer",
            "format": "int64",
            "description": "Number of 'Sad' reactions"
          },
          "angryCount": {
            "type": "integer",
            "format": "int64",
            "description": "Number of 'Angry' reactions"
          }
        },
        "required": [
          "likeCount",
          "loveCount",
          "hahaCount",
          "wowCount",
          "sadCount",
          "angryCount"
        ]
      },
      "NewsAggregatorSourceEngagementMetrics": {
        "type": "object",
        "description": "Engagement metrics for news aggregator platforms",
        "properties": {
          "digsCount": {
            "type": "integer",
            "format": "int64",
            "description": "Number of 'Digs' on aggregator sites"
          },
          "burrowsCount": {
            "type": "integer",
            "format": "int64",
            "description": "Number of 'Burrows' on aggregator sites"
          }
        },
        "required": [
          "digsCount",
          "burrowsCount"
        ]
      },
      "TwitterSourceEngagementMetrics": {
        "type": "object",
        "description": "Engagement metrics for Twitter",
        "properties": {
          "retweetsCount": {
            "type": "integer",
            "format": "int64",
            "description": "Number of retweets"
          },
          "favouritesCount": {
            "type": "integer",
            "format": "int64",
            "description": "Number of favourites"
          }
        },
        "required": [
          "retweetsCount",
          "favouritesCount"
        ]
      },
      "Review": {
        "type": "object",
        "description": "Review-specific content carried by a mention",
        "properties": {
          "rating": {
            "$ref": "#/components/schemas/Rating",
            "nullable": true,
            "description": "Rating given by the review's author, when the review includes one"
          }
        }
      },
      "Rating": {
        "type": "object",
        "description": "Rating given by the mention's author, available for review sources\n(e.g. Google Maps reviews). Always includes the raw value. The scaled\ninterpretation (bounds and percentage) is present only when the source\ndefines a bounded scale.\n",
        "properties": {
          "value": {
            "type": "number",
            "format": "double",
            "example": 4,
            "description": "Rating value in the source's original units (e.g. 4 for a 4-star review)"
          },
          "scale": {
            "$ref": "#/components/schemas/RatingScale",
            "nullable": true,
            "description": "Rating scale bounds and the value's position on that scale as a\npercentage. Present for sources with a bounded scale (e.g. Google\nMaps); absent for sources that report only a raw value.\n"
          }
        },
        "required": [
          "value"
        ]
      },
      "RatingScale": {
        "type": "object",
        "description": "Rating scale bounds and the value's normalized position on that scale",
        "properties": {
          "min": {
            "type": "number",
            "format": "double",
            "example": 1,
            "description": "Lowest possible rating value in the source's scale"
          },
          "max": {
            "type": "number",
            "format": "double",
            "example": 5,
            "description": "Highest possible rating value in the source's scale"
          },
          "percent": {
            "type": "number",
            "format": "double",
            "example": 75,
            "description": "Rating normalized to a 0-100 percentage scale, where 0 corresponds to min and 100 to max"
          }
        },
        "required": [
          "min",
          "max",
          "percent"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "description": "Generic error response",
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message describing what went wrong"
          }
        },
        "required": [
          "message"
        ]
      },
      "ValidationErrorResponse": {
        "type": "object",
        "description": "Error response for invalid request fields",
        "properties": {
          "message": {
            "type": "string",
            "description": "General validation error message"
          },
          "requestFieldErrors": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "description": "Mapping of field names to lists of validation error messages"
          }
        },
        "required": [
          "message",
          "requestFieldErrors"
        ]
      },
      "Coordinates": {
        "type": "object",
        "description": "Geographic coordinates",
        "properties": {
          "latitude": {
            "type": "number",
            "format": "double",
            "description": "Latitude coordinate"
          },
          "longitude": {
            "type": "number",
            "format": "double",
            "description": "Longitude coordinate"
          }
        },
        "required": [
          "latitude",
          "longitude"
        ]
      },
      "Country": {
        "type": "object",
        "description": "Country information",
        "properties": {
          "code": {
            "type": "string",
            "description": "ISO 3166 country code"
          }
        },
        "required": [
          "code"
        ]
      },
      "Location": {
        "type": "object",
        "description": "Geographical location details of the mention",
        "properties": {
          "coordinates": {
            "$ref": "#/components/schemas/Coordinates",
            "nullable": true,
            "description": "Geographic coordinates if available"
          },
          "country": {
            "$ref": "#/components/schemas/Country",
            "nullable": true,
            "description": "Country information if available"
          },
          "region": {
            "type": "string",
            "nullable": true,
            "description": "Region or state name"
          },
          "city": {
            "type": "string",
            "nullable": true,
            "description": "City name"
          }
        }
      },
      "SocialChannel": {
        "type": "object",
        "description": "Information about a social media channel (eg. FB Fanpage, YouTube Channel, IG Profile) the mention is coming from.",
        "properties": {
          "id": {
            "type": "string",
            "nullable": true,
            "description": "Unique identifier of the social channel"
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "Name of the social channel"
          }
        }
      },
      "Source": {
        "type": "object",
        "description": "Metadata about the source of a mention",
        "properties": {
          "socialChannel": {
            "$ref": "#/components/schemas/SocialChannel",
            "description": "Information about the source social channel"
          },
          "mentionUrl": {
            "type": "string",
            "description": "URL to the mention in a source platform (eg. https://facebook.com/post/123456789)"
          },
          "type": {
            "$ref": "#/components/schemas/SourceType",
            "description": "Type of source platform"
          }
        },
        "required": [
          "socialChannel",
          "mentionUrl",
          "type"
        ]
      },
      "AuthorGender": {
        "type": "string",
        "description": "Gender of the author",
        "enum": [
          "Male",
          "Female",
          "Unspecified"
        ]
      },
      "AuthorInfluenceMetrics": {
        "type": "object",
        "description": "Metrics related to author's influence",
        "properties": {
          "followerCount": {
            "type": "integer",
            "format": "int64",
            "nullable": true,
            "description": "Number of followers"
          },
          "fanCount": {
            "type": "integer",
            "format": "int64",
            "nullable": true,
            "description": "Number of fans"
          }
        }
      },
      "Author": {
        "type": "object",
        "description": "Information about the author of a mention",
        "properties": {
          "id": {
            "type": "string",
            "nullable": true,
            "description": "Unique identifier of the author"
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "Display name of the author"
          },
          "avatar": {
            "$ref": "#/components/schemas/Attachment",
            "nullable": true,
            "description": "Author's avatar image"
          },
          "gender": {
            "$ref": "#/components/schemas/AuthorGender",
            "description": "Gender of the author"
          },
          "influenceMetrics": {
            "$ref": "#/components/schemas/AuthorInfluenceMetrics",
            "description": "Metrics related to author's influence"
          }
        },
        "required": [
          "gender",
          "influenceMetrics"
        ]
      },
      "AttachmentType": {
        "type": "string",
        "description": "Type of attachment",
        "enum": [
          "Image",
          "Video",
          "Other"
        ]
      },
      "Attachment": {
        "type": "object",
        "description": "Details of a single attachment associated with a mention",
        "properties": {
          "url": {
            "type": "string",
            "description": "URL to the attachment"
          },
          "type": {
            "$ref": "#/components/schemas/AttachmentType",
            "description": "Type of attachment"
          }
        },
        "required": [
          "url",
          "type"
        ]
      },
      "DiscussionAuthor": {
        "type": "object",
        "description": "Author of the discussion thread",
        "properties": {
          "name": {
            "type": "string",
            "description": "Name of the discussion author"
          }
        },
        "required": [
          "name"
        ]
      },
      "Discussion": {
        "type": "object",
        "description": "Details of the discussion thread the mention belongs to",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier of the discussion thread"
          },
          "author": {
            "$ref": "#/components/schemas/DiscussionAuthor",
            "nullable": true,
            "description": "Author who started the discussion thread (optional)"
          }
        },
        "required": [
          "id"
        ]
      },
      "DeprecatedV1Fields": {
        "type": "object",
        "description": "**DEPRECATED - This field will be removed in a future API version.**\n\nContains legacy identifiers from the V1 API (https://sentione.com/api). This field is provided solely\nto assist with data migration from V1 to V2 API. Use it to match historical\ndata extracted via the legacy V1 API with current V2 responses.\n\n**Important:** Do not build any business logic upon this field. It is\nintended only for one-time data reconciliation during migration and will\nbe removed in a future without further notice.\n",
        "properties": {
          "id": {
            "type": "string",
            "description": "Mention ID as it was returned in the legacy V1 API"
          }
        },
        "required": [
          "id"
        ]
      },
      "Mention": {
        "type": "object",
        "description": "Structure representing a single mention",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier of the mention"
          },
          "author": {
            "$ref": "#/components/schemas/Author",
            "description": "Information about the mention's author"
          },
          "source": {
            "$ref": "#/components/schemas/Source",
            "description": "Source platform or site of the mention"
          },
          "discussion": {
            "$ref": "#/components/schemas/Discussion",
            "description": "Details of the discussion thread the mention belongs to"
          },
          "type": {
            "$ref": "#/components/schemas/MentionType",
            "description": "The mention type (Post, Comment, Article, PrivateMessage, Share)"
          },
          "publishedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the mention was published (ISO 8601 UTC format, e.g. 2025-05-22T14:30:00Z)"
          },
          "collectedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the mention was collected by SentiOne Listen crawlers (ISO 8601 UTC format, e.g. 2025-05-22T15:45:00Z)"
          },
          "context": {
            "$ref": "#/components/schemas/MentionContext",
            "description": "Contextual information about the mention, such as the original post,\narticle, or parent comment it references.\n"
          },
          "content": {
            "$ref": "#/components/schemas/MentionContent",
            "description": "Detailed content of the mention"
          },
          "engagementMetrics": {
            "$ref": "#/components/schemas/EngagementMetrics",
            "description": "Metrics related to engagement (likes, shares, comments, etc.)"
          },
          "location": {
            "$ref": "#/components/schemas/Location",
            "description": "Geolocation metadata if available"
          },
          "attachments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Attachment"
            },
            "description": "List of attachments (images, files) associated with the mention"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of user-defined tags assigned to the mention"
          },
          "deprecatedV1Fields": {
            "$ref": "#/components/schemas/DeprecatedV1Fields",
            "nullable": true,
            "description": "Legacy fields for V1 API migration. See DeprecatedV1Fields schema for details.\nThis field is optional and will be removed in a future.\n"
          }
        },
        "required": [
          "id",
          "author",
          "source",
          "discussion",
          "type",
          "publishedAt",
          "collectedAt",
          "content",
          "engagementMetrics",
          "attachments",
          "tags"
        ]
      },
      "StreamEvent": {
        "type": "object",
        "description": "Stream event structure for SSE and NDJSON streaming",
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "mention",
              "heartbeat"
            ],
            "description": "Type of stream event"
          },
          "data": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Mention"
              },
              {
                "$ref": "#/components/schemas/StreamHeartbeat"
              }
            ],
            "description": "Event data payload, varies by event type"
          },
          "id": {
            "type": "string",
            "description": "Unique event identifier"
          }
        },
        "required": [
          "event",
          "data",
          "id"
        ]
      },
      "StreamHeartbeat": {
        "type": "object",
        "description": "Heartbeat event to maintain connection",
        "properties": {
          "date": {
            "type": "string",
            "format": "date-time",
            "description": "Heartbeat timestamp"
          }
        },
        "required": [
          "date"
        ]
      },
      "MentionContext": {
        "type": "object",
        "description": "Contextual information about the mention, such as the original post,\narticle, or parent comment it references.\n",
        "properties": {
          "parent": {
            "$ref": "#/components/schemas/MentionParent",
            "description": "Information about the parent mention. This might be an article for sources like websites,\npost or parent comment in case of IG, FG and other social platforms. This field is optional \nand might be set to null if there's no parent or there's no relation information on particular source.\n"
          }
        }
      },
      "MentionParent": {
        "type": "object",
        "description": "Information about the parent mention. This might be an article for sources like\nwebsites, post or parent comment in case of IG, FG and other social platforms.\n",
        "properties": {
          "content": {
            "type": "object",
            "description": "Content details of the parent mention (e.g., text, title)",
            "properties": {
              "text": {
                "type": "string",
                "description": "Text body of the parent mention (optional)"
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/projects/{projectId}/mentions/recent/search/stream/live": {
      "post": {
        "summary": "Project's recent mentions live stream",
        "description": "**Tier**: Enterprise\n\n**Rate limit**: 14400 requests per hour, 2 concurrent connections\n\n**Data limitations:** \n\n* Mentions cap - monthly limit applies\n* Mentions published within last 7 days, collected by the system since the connection start (with optional 5-minute backfill)\n\n**⚠️ WARNING**: Due to limitations of readme.com API console, the **Try it out** button will not work for streaming endpoints. Please copy the generated curl command and execute it in your terminal to test streaming functionality.\n\n**⚠️ WARNING**: The order of mentions in the **live stream** is random and you cannot make any assumptions about it. Due to the nature of the **live-stream** and different delays of particular mentions, they may arrive out of chronological order.\n\n**Infinite live-stream** of mentions published within **last 7 days** which are being collected by SentiOne system from the moment the stream connection starts.\n\nSupports optional backfill of recent mentions and filtering.\nSupports both **SSE** (Server-Sent Events) and **NDJSON** (Newline Delimited JSON) formats.",
        "operationId": "recentSearchMentionsLiveStreamV2",
        "x-streaming": true,
        "tags": [
          "Mentions - Live Streams"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "Accept",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "text/event-stream",
                "application/x-ndjson"
              ]
            },
            "description": "Stream format - 'text/event-stream' for SSE or 'application/x-ndjson' for newline-delimited JSON"
          },
          {
            "name": "backfillMinutes",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0,
              "maximum": 5
            },
            "description": "Number of minutes to backfill (0-5 minutes maximum)"
          },
          {
            "name": "anonymize",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "author",
                "all"
              ]
            },
            "description": "**⚠️ Experimental** - this parameter is in experimental phase and may be changed in a future version without being considered a breaking change.\n\nEnables anonymization of personal data fields on returned mentions, allowing you to process mention data without exposing personally identifiable information — useful for compliance and data privacy requirements.\n\nAnonymized field values are replaced with a consistent hash, so the same original value always produces the same hash across all mentions.\n\nAvailable levels:\n- `author` - anonymizes author-related fields:\n  - `author.id`, `author.name` - replaced with a consistent hash\n  - `author.avatar` - set to null\n  - `discussion.author.name` - replaced with a consistent hash\n- `all` - anonymizes all identification-related fields:\n  - `author.id`, `author.name` - replaced with a consistent hash\n  - `author.avatar` - set to null\n  - `discussion.author.name` - replaced with a consistent hash\n  - `source.socialChannel.id`, `source.socialChannel.name` - replaced with a consistent hash\n  - `location` - removed entirely"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 1
            },
            "description": "Maximum number of mentions to return. When specified, the stream closes automatically after delivering the requested number of mentions. If omitted, the stream runs until the client disconnects or all matching data has been delivered."
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Search request with filters (sorting not supported for live stream - mentions arrive in random order as they are collected)",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "filters": {
                    "$ref": "#/components/schemas/LiveStreamFilters"
                  }
                }
              },
              "examples": {
                "live_stream": {
                  "summary": "Live mentions streaming with backfill",
                  "value": {
                    "filters": {
                      "type": [
                        "Post",
                        "Comment"
                      ],
                      "source": {
                        "type": [
                          "X",
                          "Reddit",
                          "Facebook"
                        ]
                      }
                    }
                  }
                },
                "live_stream_with_query_boolean": {
                  "summary": "Live stream with boolean query operators",
                  "value": {
                    "filters": {
                      "content": {
                        "query": "breaking AND (news OR announcement)"
                      },
                      "type": [
                        "Post",
                        "Comment"
                      ],
                      "source": {
                        "type": [
                          "X",
                          "Reddit",
                          "Facebook"
                        ]
                      }
                    }
                  }
                },
                "live_stream_with_query_phrase": {
                  "summary": "Live stream with phrase query operator",
                  "value": {
                    "filters": {
                      "content": {
                        "query": "\"just launched\" OR \"now available\""
                      },
                      "type": [
                        "Post"
                      ],
                      "source": {
                        "type": [
                          "X",
                          "Facebook",
                          "Instagram"
                        ]
                      }
                    }
                  }
                },
                "live_stream_with_query_wildcard": {
                  "summary": "Live stream with wildcard query operator",
                  "value": {
                    "filters": {
                      "content": {
                        "query": "launch* AND product*"
                      },
                      "type": [
                        "Post",
                        "Comment"
                      ],
                      "source": {
                        "type": [
                          "X",
                          "Reddit"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Streaming live mentions data",
            "headers": {
              "x-rate-limit-limit": {
                "description": "Limit of requests for particular API endpoint",
                "schema": {
                  "type": "integer",
                  "example": 14400
                }
              },
              "x-rate-limit-reset": {
                "description": "Unix timestamp (seconds) when limits will reset",
                "schema": {
                  "type": "integer",
                  "example": 1747666800
                }
              },
              "x-rate-limit-remaining": {
                "description": "Remaining number of requests",
                "schema": {
                  "type": "integer",
                  "example": 12000
                }
              }
            },
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "Server-Sent Events stream with the following event types:\n- `mention`: Contains live mention data (see Mention schema) - arrives in random order as collected\n- `heartbeat`: Connection heartbeat (see StreamHeartbeat schema)"
                },
                "example": "event: mention\ndata: {\"id\":\"smid-wcuEd-YCoP89RC676Z97taQ2Nk97_T5HYBbFSb1rwOCzvdVLUm5GMI6tZXFUhoU5v0zQiWgt48ZllN5iXPF9tVuU4dFDR0COkaoLAVFOrYCbXju8Nztir6cPSOMdITnpMZMjNsALWcK3MU1tevSnNpZojdQD2IzBQfzYx_o\",\"author\":{\"id\":\"facebook_user_1234567890\",\"name\":\"Sarah Johnson\",\"avatar\":{\"url\":\"https://cdn.facebook.com/avatars/user_1234567890.jpg\",\"type\":\"Image\"},\"gender\":\"Female\",\"influenceMetrics\":{\"followerCount\":245,\"fanCount\":null}},\"source\":{\"socialChannel\":{\"id\":\"facebook_page_987654321\",\"name\":\"Tech Reviews Hub\"},\"mentionUrl\":\"https://www.facebook.com/posts/123456789012345\",\"type\":\"Facebook\"},\"discussion\":{\"id\":\"sdid-Yps6OpUs2EJdRjcgbRN2MtDed7voTBB7R2fzup3w6PmL4F5YJav8DIerhXjdJRHo_yzkQx-4ow8urX31MzXdqxoKGfMiyNF9RCobV4TsiNGAn4iWBH50HDTt4EknhZV7JfQd5hvzGQKoXLeOIE6KvaizUr4j-clj74Q\",\"author\":{\"name\":\"Sarah Johnson\"}},\"type\":\"Post\",\"publishedAt\":\"2025-05-22T10:30:00Z\",\"collectedAt\":\"2025-05-22T10:32:15Z\",\"context\":{\"parent\":{\"content\":{\"text\":\"Did you see our new smartphone?\"}}},\"content\":{\"text\":\"Just tried the new smartphone and I'm really impressed! The camera quality is amazing and battery life exceeds expectations. Definitely recommend it to anyone looking for an upgrade.\",\"language\":{\"code\":\"en\"},\"sentiment\":\"Positive\"},\"engagementMetrics\":{\"influenceScore\":7,\"engagementRate\":0.125,\"sourceMetrics\":{\"common\":{\"likeCount\":28,\"shareCount\":3,\"commentCount\":12,\"viewCount\":null},\"facebook\":{\"likeCount\":28,\"loveCount\":8,\"hahaCount\":0,\"wowCount\":2,\"sadCount\":0,\"angryCount\":0},\"newsAggregators\":null,\"twitter\":null}},\"location\":{\"coordinates\":null,\"country\":{\"code\":\"US\"},\"region\":\"California\",\"city\":\"San Francisco\"},\"attachments\":[{\"url\":\"https://cdn.facebook.com/photos/smartphone_review_image.jpg\",\"type\":\"Image\"}]}\nid: live_mention_id\n\nevent: heartbeat\ndata: {\"date\": \"2025-05-22T10:30:00Z\"}\nid: 2025-05-22T10:30:00Z\n"
              },
              "application/x-ndjson": {
                "schema": {
                  "$ref": "#/components/schemas/StreamEvent"
                },
                "examples": {
                  "live_mention_event": {
                    "summary": "Live mention event",
                    "value": {
                      "event": "mention",
                      "data": {
                        "id": "smid-wcuEd-YCoP89RC676Z97taQ2Nk97_T5HYBbFSb1rwOCzvdVLUm5GMI6tZXFUhoU5v0zQiWgt48ZllN5iXPF9tVuU4dFDR0COkaoLAVFOrYCbXju8Nztir6cPSOMdITnpMZMjNsALWcK3MU1tevSnNpZojdQD2IzBQfzYx_o",
                        "author": {
                          "id": "facebook_user_1234567890",
                          "name": "Sarah Johnson",
                          "avatar": {
                            "url": "https://cdn.facebook.com/avatars/user_1234567890.jpg",
                            "type": "Image"
                          },
                          "gender": "Female",
                          "influenceMetrics": {
                            "followerCount": 245,
                            "fanCount": null
                          }
                        },
                        "source": {
                          "socialChannel": {
                            "id": "facebook_page_987654321",
                            "name": "Tech Reviews Hub"
                          },
                          "mentionUrl": "https://www.facebook.com/posts/123456789012345",
                          "type": "Facebook"
                        },
                        "discussion": {
                          "id": "sdid-Yps6OpUs2EJdRjcgbRN2MtDed7voTBB7R2fzup3w6PmL4F5YJav8DIerhXjdJRHo_yzkQx-4ow8urX31MzXdqxoKGfMiyNF9RCobV4TsiNGAn4iWBH50HDTt4EknhZV7JfQd5hvzGQKoXLeOIE6KvaizUr4j-clj74Q",
                          "author": {
                            "name": "Sarah Johnson"
                          }
                        },
                        "type": "Post",
                        "publishedAt": "2025-05-22T10:30:00Z",
                        "collectedAt": "2025-05-22T10:32:15Z",
                        "context": {
                          "parent": {
                            "content": {
                              "text": "Did you see our new smartphone?"
                            }
                          }
                        },
                        "content": {
                          "text": "Just tried the new smartphone and I'm really impressed! The camera quality is amazing and battery life exceeds expectations. Definitely recommend it to anyone looking for an upgrade.",
                          "language": {
                            "code": "en"
                          },
                          "sentiment": "Positive"
                        },
                        "engagementMetrics": {
                          "influenceScore": 7,
                          "engagementRate": 0.125,
                          "sourceMetrics": {
                            "common": {
                              "likeCount": 28,
                              "shareCount": 3,
                              "commentCount": 12,
                              "viewCount": null
                            },
                            "facebook": {
                              "likeCount": 28,
                              "loveCount": 8,
                              "hahaCount": 0,
                              "wowCount": 2,
                              "sadCount": 0,
                              "angryCount": 0
                            },
                            "newsAggregators": null,
                            "twitter": null
                          }
                        },
                        "location": {
                          "coordinates": null,
                          "country": {
                            "code": "US"
                          },
                          "region": "California",
                          "city": "San Francisco"
                        },
                        "attachments": [
                          {
                            "url": "https://cdn.facebook.com/photos/smartphone_review_image.jpg",
                            "type": "Image"
                          }
                        ]
                      },
                      "id": "smid-wcuEd-YCoP89RC676Z97taQ2Nk97_T5HYBbFSb1rwOCzvdVLUm5GMI6tZXFUhoU5v0zQiWgt48ZllN5iXPF9tVuU4dFDR0COkaoLAVFOrYCbXju8Nztir6cPSOMdITnpMZMjNsALWcK3MU1tevSnNpZojdQD2IzBQfzYx_o"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication errors",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "415": {
            "description": "Unsupported media type",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (max 14400 requests per hour)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "ApiKeyAuth": []
    }
  ]
}
```