{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Listening Query API V3 — Developer Guide","description":"Sprinklr offers robust, convenient, and simple RESTful Web service APIs to integrate data from Sprinklr to any external system.","keywords":["Sprinklr API","Sprinklr Developer Portal","OAuth 2.0","RESTful API","Social Media API","Customer Experience API","Unified-CXM","Social Listening API"]},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"listening-query-api-v3--developer-guide","__idx":0},"children":["Listening Query API V3 — Developer Guide"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Applies to:"]}," Sprinklr Listening Query API V3 — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v3/listening/query/stream"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v3/listening/query/widget"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["V2 API reference:"]}," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://legacy-dev.sprinklr.com/listening-streams"},"children":["Listening Streams | Sprinklr Developer Portal"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v2/listening/query/stream"]},")"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"1-overview","__idx":1},"children":["1. Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Sprinklr Listening"]}," gives brands visibility into online conversations across channels, websites, and news sources. Listening data is organised into ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Topics"]}," (keyword queries that pull in conversations not sent directly to your brand), ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Topic Groups"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Themes"]},", and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Keyword Lists"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Listening Query API V3 lets you run two fundamentally different kinds of query against that data:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"You want"},"children":["You want"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Endpoint"},"children":["Endpoint"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Returns"},"children":["Returns"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The individual messages that matched a Listening query"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v3/listening/query/stream"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A paginated list of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Message"]}," objects"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An aggregated count, breakdown, or trend over those messages"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v3/listening/query/widget"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Aggregated buckets (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["word"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["count"]},")"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both endpoints take the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["same request body schema"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ApiWidgetRequestDTO"]}," in the specification). The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details.widgetType"]}," field is what decides which shape of answer you get — and it is also what decides which of the two endpoints you must call."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"11-the-query-model","__idx":2},"children":["1.1 The query model"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every Listening query, on either endpoint, is built from four parts:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Part"},"children":["Part"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Purpose"},"children":["Purpose"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Time range"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sinceTime"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["untilTime"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeField"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timezoneOffset"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Which window of messages to consider"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Scope"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filters[]"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Which Listening dimensions (Topic, Sentiment, Media Source, …) narrow the set"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Shape"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["What kind of answer you want — stream of messages, distribution, trend, users, topic cluster"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Measure"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metric"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["trendAggregationPeriod"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["What is being counted, and at what granularity"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Learn this once and both endpoints become the same API with two output modes."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"12-prerequisite-listening-must-be-enabled","__idx":3},"children":["1.2 Prerequisite: Listening must be enabled"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Listening is one of a small number of Sprinklr data sets that is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," enabled by default. Per the Sprinklr Help Center, Listening API access requires an explicit request to the Support team when Listening is part of the use case listed in your License Order Form."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If Listening Stream is not enabled, the response body carries:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"message\": \"Streaming in listening is not enabled for you. Please contact support\",\n  \"data\": {}\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"2-base-urls-and-environments","__idx":4},"children":["2. Base URLs and environments"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All API calls are sent to the production endpoint:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"https://api3.sprinklr.com/{env}/api/v3\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["So the listening resource in production is:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"https://api3.sprinklr.com/{env}/api/v3/listening/query/stream\nhttps://api3.sprinklr.com/{env}/api/v3/listening/query/widget\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the environment list at ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://legacy-dev.sprinklr.com/apis"},"children":["APIs | Sprinklr Developer Portal"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"3-authentication-and-common-headers","__idx":5},"children":["3. Authentication and common headers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All Listening API calls are authenticated with OAuth 2.0. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://legacy-dev.sprinklr.com/api-overview"},"children":["API Overview"]}," for portal registration, API key and secret generation, and the Authorize flow."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Key"},"children":["Key"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Value"},"children":["Value"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required on"},"children":["Required on"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Bearer {{accessToken}}"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Credential used by the API to authenticate a user with the server. For generating the authorization token, refer to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Authorize"]}," section on the developer portal."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["All requests"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Key"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{{apiKey}}"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["API key that authenticates the application with the server. For generating an API key, refer to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Getting Started"]}," guide."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["All requests"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Content-Type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/json"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Representation header that determines the type of data present in the request body."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["All requests (both endpoints are ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," with a required body)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Accept"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/json"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Determines the acceptable response type from the server."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["All requests"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Governance."]}," Sprinklr's API governance model is tied directly to the user's role and permissions — the API key inherits every permission of the user it was created for. A caller with no visibility of a Listening Topic will not receive its messages, regardless of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filterValues"]}," sent."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Credential hygiene."]}," Never commit an access token or API key to source control, never paste one into a ticket or chat, and never log the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Key"]}," header values. Every credential in this guide is a placeholder. If a real token or key has been exposed, revoke and regenerate it immediately."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"4-post-apiv3listeningquerystream--query-listening-stream","__idx":6},"children":["4. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v3/listening/query/stream"]}," — Query Listening Stream"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Operation ID:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ListeningApiV3_queryStream"]}," · ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Tag:"]}," Listening V3 · ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Request body:"]}," required"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Returns the message stream associated with each matching message, containing the required information. It returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["StreamWidgetResponse"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ListeningStreamV3ResponseDTO"]}," in the V3 specification)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this endpoint when you need the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["messages themselves"]}," — text, author, permalink, workflow state, enrichments — rather than a count."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"41-volume-limits","__idx":7},"children":["4.1 Volume limits"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These are hard limits carried forward verbatim from the V2 reference and repeated in the supplied V3 specification:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["You cannot fetch more than 10,000 messages in a same timestamp."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["You cannot fetch more than 1,000 messages in one request."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Design your pagination around both numbers. The second caps a single call; the first caps how deep you can page within one timestamp before you must advance the time window (",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#92-export-a-full-day-of-mentions-safely"},"children":["§9.2"]},")."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"42-request-body","__idx":8},"children":["4.2 Request body"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Sub-parameter"},"children":["Sub-parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sinceTime"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Long"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Start of the time range, in epoch milliseconds."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["untilTime"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Long"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["End of the time range, in epoch milliseconds."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeField"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Which time the range applies to. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SN_CREATED_TIME"]}," — time the message was created on the social network (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["default"]},"). ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SYSTEM_CREATED_TIME"]}," — time the message was created in Sprinklr."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timezoneOffset"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Long"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Client timezone UTC offset in milliseconds. Default ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0"]}," (UTC). For example, EST is UTC−5, so ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["-(5*60*60*1000)"]}," = ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["-18000000"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Widget configuration. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#43-the-details-object-stream"},"children":["§4.3"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["widgetType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["STREAM"]}," for this endpoint."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filters"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Array of objects"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Dimension filters applied to the query. Default: empty. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#44-the-filters-array"},"children":["§4.4"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metric"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Metric to aggregate. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MENTIONS"]}," (default), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REACH"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RETWEETS"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAVORITES"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["start"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Pagination offset. Default ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0"]},". Applicable to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["STREAM"]}," widget only."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rows"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Maximum number of items in the page. Default ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["20"]},". Applicable to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["STREAM"]}," widget only. Bounded by the 1,000-messages-per-request limit in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#41-volume-limits"},"children":["§4.1"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sortKey"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Field used to sort the returned messages. Takes three values: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SYSTEM_CREATED_TIME"]}," (system created time), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CREATED_TIME"]}," (social network created time), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MODIFIED_TIME"]}," (modified time). Default: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CREATED_TIME"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sortOrder"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Sort direction. Stream endpoint only."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["messageFormatOptions"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Comma-delimited formatting values: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["strip_html"]}," (strip HTML from message text), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["strip_url"]}," (strip URLs from message text), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["include_original"]}," (also return the original text in an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["originalText"]}," field)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["trendAggregationPeriod"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Trend bucket size — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HOUR"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DAY"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WEEK"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MONTH"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["QUARTER"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YEAR"]},". Applicable to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TREND"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GROUPED_TREND"]}," widgets, not to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["STREAM"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["echoRequest"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},", echoes the request back in the response object."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tag"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A state parameter, usable as a version attached with the response. It is not modified by the API and is returned as-is."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"43-the-details-object-stream","__idx":9},"children":["4.3 The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details"]}," object (stream)"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required/Optional"},"children":["Required/Optional"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["widgetType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Refers to the type of the widget. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["STREAM"]}," on this endpoint."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"44-the-filters-array","__idx":10},"children":["4.4 The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filters[]"]}," array"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Shared by both endpoints."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required/Optional"},"children":["Required/Optional"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dimension"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Filter dimension such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOPIC"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOPIC_GROUP"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SENTIMENT"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MEDIA_SOURCE"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filterValues"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Array of String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["List of IDs for the given dimension. For the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOPIC"]}," dimension, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filterValues"]}," is the list of Topic IDs."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["exclude"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Excludes matching values when set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},". Default ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customFieldName"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required when filtering on custom field dimensions."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To resolve a Topic ID, use the Listening Topic APIs — for example ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://legacy-dev.sprinklr.com/read-topic-2-0"},"children":["Read Topic 2.0"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v2/listening-topic/{topicId}"]},"), or the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Listening Topic V3"]}," endpoints (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/listening/topic"]},") in the V3 specification. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filterValues"]}," takes IDs, never names."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"45-example-request","__idx":11},"children":["4.5 Example request"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl --location 'https://api3.sprinklr.com/api/v3/listening/query/stream' \\\n--header 'Authorization: Bearer {{accessToken}}' \\\n--header 'Key: {{apiKey}}' \\\n--header 'Content-Type: application/json' \\\n--header 'Accept: application/json' \\\n--data '{\n    \"sinceTime\": 1488034511000,\n    \"untilTime\": 1786537500000,\n    \"details\": {\n      \"widgetType\": \"STREAM\"\n    },\n    \"filters\": [\n      {\n        \"dimension\": \"TOPIC\",\n        \"filterValues\": [\"6a7ae25c298255388c56550a\"]\n      }\n    ],\n    \"metric\": \"MENTIONS\",\n    \"rows\": 10,\n    \"start\": 0\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"46-example-response","__idx":12},"children":["4.6 Example response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Illustrative example, reproduced from the supplied specification. Not real customer data and not a guaranteed production response."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"data\": {\n        \"result\": [\n            {\n                \"sourceType\": \"ACCOUNT\",\n                \"sourceId\": 600049002,\n                \"content\": {\n                    \"text\": \"\",\n                    \"isRichText\": false\n                },\n                \"channelMessageId\": \"p234uqy\",\n                \"channelType\": \"REDDIT\",\n                \"accountType\": \"SUBREDDIT\",\n                \"channelCreatedTime\": 1786033040000,\n                \"senderProfile\": {\n                    \"channelType\": \"REDDIT\",\n                    \"followers\": -1,\n                    \"following\": -1,\n                    \"unSubscribed\": false,\n                    \"deleted\": false,\n                    \"snCreatedTime\": 0,\n                    \"snModifiedTime\": 0,\n                    \"statusCount\": -1,\n                    \"accountSpecificInfos\": []\n                },\n                \"permalink\": \"https://www.reddit.com/r/holup/comments/1vh6sg3/natasha/p234uqy\",\n                \"language\": \"en\",\n                \"messageId\": \"ACCOUNT_600049002_1786033040000_REDDIT_273_p234uqy\",\n                \"brandPost\": false,\n                \"createdTime\": 1786033605300,\n                \"modifiedTime\": 1786348560798,\n                \"textEntities\": {},\n                \"insights\": {},\n                \"workflow\": {\n                    \"modifiedTime\": 1786348560798,\n                    \"customProperties\": {},\n                    \"queues\": [],\n                    \"spaceWorkflows\": []\n                },\n                \"enrichments\": {},\n                \"autoImported\": false,\n                \"autoResponse\": false,\n                \"apiStatus\": \"Removed fields because of resyndication policy\"\n            }\n        ],\n        \"hasMore\": true\n    },\n    \"errors\": []\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"47-response-envelope","__idx":13},"children":["4.7 Response envelope"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Contains the API response data."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.result"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Array"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["List of messages/posts matching the query criteria."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.hasMore"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Indicates whether additional records are available for retrieval through pagination."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Array"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Contains any errors returned by the API. An empty array indicates a successful request."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This matches ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ListeningStreamV3ResponseDTO"]}," in the specification, which defines exactly two properties — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]}," (array of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Message"]},") and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hasMore"]}," (boolean)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"48-message-object--dataresult","__idx":14},"children":["4.8 Message object — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.result[]"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Sub-parameter"},"children":["Sub-parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sourceType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Type of source from which the message was collected (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCOUNT"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sourceId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Long"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unique identifier of the source account."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Contains the content of the message."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["text"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Text content of the message. May be empty due to platform resyndication policies."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["isRichText"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Indicates whether the content contains rich text formatting."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channelMessageId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unique identifier of the message on the native channel."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channelType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Social channel from which the message originated, such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REDDIT"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TWITTER"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Specifies the subtype of the message within the social channel, such as a post, comment, reply, mention, or repost."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accountType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Type of account associated with the message, such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SUBREDDIT"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TWITTER"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channelCreatedTime"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Long"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Timestamp (in milliseconds) when the message was originally created on the source channel."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["senderProfile"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Metadata associated with the message author."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["senderProfile"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channelType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Social channel associated with the sender profile."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["senderProfile"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["followers"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Number of followers for the sender profile. A value of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["-1"]}," indicates unavailable data."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["senderProfile"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["following"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Number of accounts followed by the sender profile. A value of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["-1"]}," indicates unavailable data."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["senderProfile"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unSubscribed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Indicates whether the profile is unsubscribed."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["senderProfile"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["deleted"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Indicates whether the profile has been deleted."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["senderProfile"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["snCreatedTime"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Long"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Timestamp when the sender profile was created on the social network."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["senderProfile"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["snModifiedTime"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Long"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Timestamp when the sender profile was last updated on the social network."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["senderProfile"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["statusCount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Total number of posts/messages by the sender. A value of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["-1"]}," indicates unavailable data."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["senderProfile"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accountSpecificInfos"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Array"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Channel-specific metadata for the sender profile."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["permalink"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Direct link to the original message or post on the social platform."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["language"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Detected language of the message content."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["messageId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unique Sprinklr message identifier."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["brandPost"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Indicates whether the message was published by a brand-owned account."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createdTime"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Long"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Timestamp (in milliseconds) when the message was ingested into Sprinklr."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["modifiedTime"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Long"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Timestamp (in milliseconds) when the message was last updated in Sprinklr."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["textEntities"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Contains extracted entities such as people, locations, organizations, hashtags, URLs, and mentions from the message content."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["insights"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Stores analytics, classifications, and insights generated for the message."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["workflow"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Workflow information associated with the message."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["workflow"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["modifiedTime"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Long"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Timestamp of the most recent workflow update."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["workflow"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customProperties"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Custom properties and user-defined fields applied to the message."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["workflow"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["queues"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Array"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Lists queues to which the message has been assigned."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["workflow.queues[]"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["queueId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Long"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unique identifier of the assigned queue."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["workflow.queues[]"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["assignmentTime"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Long"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Timestamp when the message was assigned to the queue."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["workflow"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["spaceWorkflows"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Array"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Contains workflow information associated with Spaces."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enrichments"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Additional enrichment data applied to the message."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["autoImported"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Indicates whether the message was automatically imported into the platform."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["autoResponse"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Indicates whether an automatic response was sent for the message."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiStatus"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Provides status or informational messages related to the API response, such as content restrictions due to platform resyndication policies."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The V3 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Message"]}," schema in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sprinklr-v3.yaml"]}," additionally defines ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["draftId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["receiverProfile"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mentionedProfiles"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["postId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["assetId"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authorId"]},". These are part of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Message"]}," type but do not appear in the supplied Listening Stream examples — treat their presence in a Listening stream response as unconfirmed."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"apistatus-and-empty-content","__idx":15},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiStatus"]}," and empty content"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the supplied example every message returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"content\": {\"text\": \"\"}"]}," alongside ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"apiStatus\": \"Removed fields because of resyndication policy\""]},". ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["This is expected behaviour, not a defect."]}," Channel resyndication policies (notably Twitter/X) restrict which fields Sprinklr may return over the API. Enabling full Twitter syndication requires an explicit request to Sprinklr Support, per the Sprinklr Help Center."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Always read ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiStatus"]}," before treating an empty ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content.text"]}," as \"no text\"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"5-post-apiv3listeningquerywidget--query-listening-widget","__idx":16},"children":["5. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v3/listening/query/widget"]}," — Query Listening Widget"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Operation ID:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ListeningApiV3_queryWidget"]}," · ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Tag:"]}," Listening V3 · ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Request body:"]}," required"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Queries Listening widget data — distribution, grouped distribution, trend, users, and topic cluster. Use this endpoint for ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["aggregates"]},", never for raw messages."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"51-request-body","__idx":17},"children":["5.1 Request body"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sinceTime"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["long"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Start of time range (epoch milliseconds)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["untilTime"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["long"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["End of time range (epoch milliseconds)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timezoneOffset"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["long"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Client timezone offset in milliseconds."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Widget configuration. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#52-the-details-object-widget"},"children":["§5.2"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filters"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["array of objects"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Dimension filters (default empty). See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#44-the-filters-array"},"children":["§4.4"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metric"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Metric to aggregate (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MENTIONS"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REACH"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RETWEETS"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAVORITES"]},"). Default ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MENTIONS"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["trendAggregationPeriod"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bucket size for trend widgets (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HOUR"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DAY"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WEEK"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MONTH"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["QUARTER"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YEAR"]},"). Required for trend types."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["messageFormatOptions"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Message formatting options passed to the widget engine."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["start"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Pagination offset (default ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rows"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Page size (default ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["20"]},"). Max depends on widget type (distribution ≤ 100, grouped distribution ≤ 20)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sortKey"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not used on widget endpoint (stream only)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sortOrder"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not used on widget endpoint (stream only)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeField"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Time field for filtering (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SN_CREATED_TIME"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SYSTEM_CREATED_TIME"]},"). Default ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SN_CREATED_TIME"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["echoRequest"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},", echoes the request in the response metadata."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tag"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Client-side request version tag (not modified by API)."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"52-the-details-object-widget","__idx":18},"children":["5.2 The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details"]}," object (widget)"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required/Optional"},"children":["Required/Optional"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["widgetType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Widget type. Supported values include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DISTRIBUTION"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GROUPED_DISTRIBUTION"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TREND"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GROUPED_TREND"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USERS"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOPIC_CLUSTER"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required for the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USERS"]}," widget type."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dimension"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Primary dimension for the widget. For example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SENTIMENT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOPIC"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MEDIA_SOURCE"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["otherDimension"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Secondary dimension. Required for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GROUPED_DISTRIBUTION"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["otherDimensionRows"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Maximum number of rows for the secondary dimension. Default is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["20"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customFieldName"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Custom field name when the selected dimension references custom fields."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"which-fields-each-widgettype-needs","__idx":19},"children":["Which fields each ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["widgetType"]}," needs"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"widgetType"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["widgetType"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"dimension"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dimension"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"otherDimension"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["otherDimension"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"subType"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subType"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"trendAggregationPeriod"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["trendAggregationPeriod"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"rows ceiling"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rows"]}," ceiling"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DISTRIBUTION"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["≤ 100"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GROUPED_DISTRIBUTION"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Required"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["≤ 20"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TREND"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Required"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not specified"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GROUPED_TREND"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Required"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not specified"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USERS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Required"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not specified"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOPIC_CLUSTER"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not specified"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["STREAM"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Not supported here"]}," — use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/listening/query/stream"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Derived from the conditionality notes in the supplied widget specification. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rows"]}," ceilings for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TREND"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GROUPED_TREND"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USERS"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOPIC_CLUSTER"]}," are not stated in any supplied source — confirm before relying on large page sizes."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"53-example-request","__idx":20},"children":["5.3 Example request"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST 'https://api3.sprinklr.com/api/v3/listening/query/widget' \\\n  -H 'Authorization: Bearer {{accessToken}}' \\\n  -H 'Key: {{apiKey}}' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"sinceTime\": 1488034511000,\n    \"untilTime\": 1490972111000,\n    \"details\": {\n      \"widgetType\": \"DISTRIBUTION\",\n      \"dimension\": \"SENTIMENT\"\n    },\n    \"filters\": [\n      {\n        \"dimension\": \"TOPIC\",\n        \"filterValues\": [\"595c50dbe4b064e21f85d074\"]\n      }\n    ],\n    \"metric\": \"MENTIONS\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"54-example-response","__idx":21},"children":["5.4 Example response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Illustrative example, reproduced from the supplied specification."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"data\": [\n    {\n      \"word\": \"Twitter\",\n      \"id\": \"TWITTER\",\n      \"count\": 21,\n      \"values\": {},\n      \"additional\": {}\n    },\n    {\n      \"word\": \"Blogs/Websites\",\n      \"id\": \"BLOGS\",\n      \"count\": 9,\n      \"values\": {},\n      \"additional\": {}\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"55-response-parameters","__idx":22},"children":["5.5 Response parameters"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Array"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Widget data returned by the API."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data[].word"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Display label of the result bucket."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data[].id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unique identifier for the bucket."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data[].count"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Long"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Aggregated metric count."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data[].values"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Additional metric breakdown values."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data[].additional"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Additional metadata associated with the bucket."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"6-response-format-and-status-codes","__idx":23},"children":["6. Response format and status codes"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"61-envelopes-at-a-glance","__idx":24},"children":["6.1 Envelopes at a glance"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Endpoint"},"children":["Endpoint"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Envelope"},"children":["Envelope"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Result location"},"children":["Result location"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"More-pages flag"},"children":["More-pages flag"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/listening/query/stream"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ \"data\": { \"result\": [], \"hasMore\": bool }, \"errors\": [] }"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.result"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.hasMore"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/listening/query/widget"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ \"data\": [ … ] }"]}," per example; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["APIResponse"]}," per specification"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not documented"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"62-the-errors-array","__idx":25},"children":["6.2 The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," array"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sprinklr-v3.yaml"]}," defines each ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Error"]}," with three ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["required"]}," properties:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["24-character hex ObjectId"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Error code"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Dotted error key (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["account.not.found"]},")"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Because ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}," is a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["dotted error key"]}," rather than prose, do not surface it directly to end users. Map codes to your own copy."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"63-response-codes","__idx":26},"children":["6.3 Response codes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both operations declare the same responses in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sprinklr-v3.yaml"]},":"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"HTTP Code"},"children":["HTTP Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Scenario"},"children":["Scenario"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200 OK"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Success"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Query executed; results returned in the envelope."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400 Bad Request"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid request"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Malformed body, missing required field, or an invalid ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["widgetType"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dimension"]}," combination."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401 Unauthorized"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authentication failed"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid or missing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," token."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403 Forbidden"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Insufficient permissions"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The API key's user lacks permission on the requested Listening data."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404 Not Found"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not found"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Referenced resource not found."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500 Internal Server Error"]}," is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," declared on these two operations in the supplied specification. Still handle it — but note the specification omission (",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#12-questions-for-the-api-owner"},"children":["§12"]},")."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always inspect the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," array even on a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"7-v2--v3-migration","__idx":27},"children":["7. V2 → V3 migration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This section is for developers already running against ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v2/listening/query/stream"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"71-the-headline-almost-nothing-changes","__idx":28},"children":["7.1 The headline: almost nothing changes"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v2/listening/query/stream"]}," — path simplified"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Request body fields (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sinceTime"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["untilTime"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filters"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rows"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["start"]},", etc.) ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["remain unchanged"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Response wrapped in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ \"data\": { \"result\": [...] }, \"errors\": [] }"]}," envelope — ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["already V3 compliant, no change needed"]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["So for the stream endpoint the migration is, in the common case, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["a base-URL change and nothing else"]},". Your existing V2 request bodies and your existing V2 response-parsing code both continue to work."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"72-endpoint-mapping","__idx":29},"children":["7.2 Endpoint mapping"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"V2"},"children":["V2"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"V3"},"children":["V3"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v2/listening/query/stream"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v3/listening/query/stream"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["No documented V2 equivalent in the supplied sources"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v3/listening/query/widget"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The widget endpoint is the new capability in this release. The V2 Listening Streams page documents ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["widgetType"]}," values for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TREND"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GROUPED_TREND"]}," in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["trendAggregationPeriod"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"8-dimensions-metrics-and-widget-types--reference","__idx":30},"children":["8. Dimensions, metrics, and widget types — reference"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Values below are only those attested in the supplied sources. These lists are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not exhaustive"]},"; the widget specification says \"Supported values include\"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details.widgetType"]}]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["STREAM"]}," (stream endpoint only), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DISTRIBUTION"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GROUPED_DISTRIBUTION"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TREND"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GROUPED_TREND"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USERS"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOPIC_CLUSTER"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metric"]}]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MENTIONS"]}," (default), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REACH"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RETWEETS"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAVORITES"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filters[].dimension"]}]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOPIC"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOPIC_GROUP"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SENTIMENT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MEDIA_SOURCE"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details.dimension"]}]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SENTIMENT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOPIC"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MEDIA_SOURCE"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeField"]}]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SN_CREATED_TIME"]}," (default), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SYSTEM_CREATED_TIME"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sortKey"]}]}," (stream only) — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CREATED_TIME"]}," (default), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SYSTEM_CREATED_TIME"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MODIFIED_TIME"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["trendAggregationPeriod"]}]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HOUR"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DAY"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WEEK"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MONTH"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["QUARTER"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YEAR"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["messageFormatOptions"]}]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["strip_html"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["strip_url"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["include_original"]}," (comma-delimited)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channelType"]}]}," values seen in responses — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REDDIT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TWITTER"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INSTAGRAM"]},"; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accountType"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SUBREDDIT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TWITTER"]},"; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sourceType"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCOUNT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LISTENING"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"9-use-cases","__idx":31},"children":["9. Use cases"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"91-replace-client-side-counting-with-a-distribution-widget","__idx":32},"children":["9.1 Replace client-side counting with a distribution widget"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Scenario:"]}," you currently page the whole stream for a Topic just to count mentions by sentiment."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Stop. Call the widget endpoint once:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"sinceTime\": 1488034511000,\n  \"untilTime\": 1490972111000,\n  \"details\": { \"widgetType\": \"DISTRIBUTION\", \"dimension\": \"SENTIMENT\" },\n  \"filters\": [{ \"dimension\": \"TOPIC\", \"filterValues\": [\"595c50dbe4b064e21f85d074\"] }],\n  \"metric\": \"MENTIONS\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["One request replaces an unbounded pagination loop, and it is unaffected by the 1,000-per-request stream cap."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"92-export-a-full-day-of-mentions-safely","__idx":33},"children":["9.2 Export a full day of mentions safely"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Scenario:"]}," nightly export of every mention on a Topic."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The two limits in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#41-volume-limits"},"children":["§4.1"]}," interact. A single request returns at most 1,000 messages, and you cannot fetch more than 10,000 messages ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["in a same timestamp"]},". So:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Split the day into windows using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sinceTime"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["untilTime"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Within a window, page with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["start"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rows"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rows"]}," ≤ 1,000)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Continue while ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.hasMore"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If a window approaches 10,000 messages, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["narrow the window"]}," rather than paging deeper."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Pin ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeField"]}," explicitly — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SN_CREATED_TIME"]}," for \"when it was posted\", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SYSTEM_CREATED_TIME"]}," for \"when Sprinklr saw it\". A backfill will scatter across the two very differently."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"async function fetchWindow(sinceTime, untilTime, topicId) {\n  const rows = 1000;                 // per-request maximum\n  let start = 0;\n  const all = [];\n\n  while (true) {\n    const res = await post('/api/v3/listening/query/stream', {\n      sinceTime, untilTime,\n      timeField: 'SN_CREATED_TIME',\n      details: { widgetType: 'STREAM' },\n      filters: [{ dimension: 'TOPIC', filterValues: [topicId] }],\n      metric: 'MENTIONS',\n      sortKey: 'CREATED_TIME',\n      rows, start\n    });\n\n    if (res.errors && res.errors.length) {\n      handleErrors(res.errors);      // dotted keys, e.g. account.not.found\n      break;\n    }\n\n    all.push(...res.data.result);\n    if (!res.data.hasMore) break;    // note: nested under data, not at root\n\n    start += rows;\n    if (start >= 10000) {            // same-timestamp ceiling — narrow the window\n      throw new Error('Window too dense; split the time range');\n    }\n  }\n  return all;\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"93-idempotent-incremental-sync","__idx":34},"children":["9.3 Idempotent incremental sync"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Scenario:"]}," poll every 15 minutes for new mentions."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeField: \"SYSTEM_CREATED_TIME\""]}," and window on Sprinklr's ingestion time, not the social network's. A message posted three days ago but ingested five minutes ago will be missed entirely by an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SN_CREATED_TIME"]}," window — this is the single most common cause of \"the API is dropping messages\" reports."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tag"]}," to stamp each poll with your own cursor version; the API returns it unchanged, which makes correlating a response to the request that produced it trivial in logs."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"94-build-a-sentiment-by-channel-matrix","__idx":35},"children":["9.4 Build a sentiment-by-channel matrix"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Scenario:"]}," a dashboard cell showing sentiment split within each media source."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"sinceTime\": 1488034511000,\n  \"untilTime\": 1490972111000,\n  \"details\": {\n    \"widgetType\": \"GROUPED_DISTRIBUTION\",\n    \"dimension\": \"MEDIA_SOURCE\",\n    \"otherDimension\": \"SENTIMENT\",\n    \"otherDimensionRows\": 5\n  },\n  \"filters\": [{ \"dimension\": \"TOPIC\", \"filterValues\": [\"595c50dbe4b064e21f85d074\"] }],\n  \"metric\": \"MENTIONS\",\n  \"rows\": 20\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GROUPED_DISTRIBUTION"]}," caps ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rows"]}," at ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["20"]},". Do not request more."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"95-plot-a-volume-trend","__idx":36},"children":["9.5 Plot a volume trend"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Scenario:"]}," daily mention volume over a quarter."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["widgetType: \"TREND\""]}," and — this is mandatory for trend types — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["trendAggregationPeriod: \"DAY\""]},". Omitting it is a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"sinceTime\": 1488034511000,\n  \"untilTime\": 1490972111000,\n  \"details\": { \"widgetType\": \"TREND\", \"dimension\": \"TOPIC\" },\n  \"trendAggregationPeriod\": \"DAY\",\n  \"filters\": [{ \"dimension\": \"TOPIC\", \"filterValues\": [\"595c50dbe4b064e21f85d074\"] }],\n  \"metric\": \"MENTIONS\",\n  \"timezoneOffset\": -18000000\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timezoneOffset"]}," deliberately on any trend query. It defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0"]}," (UTC), so a \"daily\" trend for a US brand will otherwise bucket on UTC midnight and shift every peak by five hours."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"96-exclude-a-noisy-sub-topic","__idx":37},"children":["9.6 Exclude a noisy sub-topic"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Scenario:"]}," a Topic is polluted by one recurring source."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add a second filter with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["exclude: true"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"\"filters\": [\n  { \"dimension\": \"TOPIC\", \"filterValues\": [\"595c50dbe4b064e21f85d074\"] },\n  { \"dimension\": \"MEDIA_SOURCE\", \"filterValues\": [\"BLOGS\"], \"exclude\": true }\n]\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"97-strip-markup-before-indexing-message-text","__idx":38},"children":["9.7 Strip markup before indexing message text"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Scenario:"]}," you are pushing message text into a search index that chokes on HTML and URLs."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["messageFormatOptions: \"strip_html,strip_url,include_original\""]},". You get clean text for indexing plus the untouched original in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["originalText"]}," for display and audit."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"98-reconcile-the-api-returns-empty-text","__idx":39},"children":["9.8 Reconcile \"the API returns empty text\""]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Scenario:"]}," support reports blank message bodies."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiStatus"]}," on the affected messages first (",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#apistatus-and-empty-content"},"children":["§4.8"]},"). ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"Removed fields because of resyndication policy\""]}," means the channel — not Sprinklr, and not your code — withheld the field. Resolution is a Sprinklr Support request to enable the relevant syndication (for example, Twitter Syndication), not a code change."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"10-caveats-and-best-practices","__idx":40},"children":["10. Caveats and best practices"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Choosing the endpoint"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Messages → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/listening/query/stream"]},". Aggregates → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/listening/query/widget"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["STREAM"]}," is not a valid ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["widgetType"]}," on the widget endpoint."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Both endpoints share one request schema. Build one request-builder, parameterise ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Volume and pagination"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Max 1,000 messages per request."]}," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Max 10,000 messages in a same timestamp."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["start"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rows"]}," apply to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["STREAM"]}," only."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Page while ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.hasMore"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," — note it is nested under ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]},", unlike other V3 APIs."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DISTRIBUTION"]}," caps ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rows"]}," at 100; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GROUPED_DISTRIBUTION"]}," caps at 20."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Time handling"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sinceTime"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["untilTime"]}," are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["epoch milliseconds"]},", not seconds and not ISO-8601."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeField"]}," defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SN_CREATED_TIME"]},". Choose it explicitly."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timezoneOffset"]}," defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0"]}," (UTC) and is expressed in milliseconds — EST is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["-18000000"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Filters"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filterValues"]}," takes ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["IDs"]},", not names. Resolve Topic IDs through the Listening Topic APIs."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["exclude: true"]}," inverts a filter; default is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customFieldName"]}," is required when filtering on custom-field dimensions."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Filter values you cannot see under governance return nothing rather than an error."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Trends"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["trendAggregationPeriod"]}," is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["required"]}," for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TREND"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GROUPED_TREND"]},", and ignored elsewhere."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Entitlement and content"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Listening is not enabled by default — it requires an explicit Support request."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Empty ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content.text"]}," with an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiStatus"]}," note is a resyndication restriction, not a bug."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["-1"]}," in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["senderProfile.followers"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["following"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["statusCount"]}," means ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["unavailable"]},", not zero. Do not sum it."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Error handling"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Inspect ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," on every response, including ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors[].message"]}," is a dotted key (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["account.not.found"]},"), not user-facing prose. Map it."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}," is not declared on these operations in the specification, but handle it anyway."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Operational"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tag"]}," round-trips unchanged — use it as a request correlation ID."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["echoRequest: true"]}," returns your request alongside the response; useful in debugging, wasteful in production."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Rate limits for these two endpoints are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not documented"]}," in any supplied source. Implement retry with exponential backoff regardless, and confirm the actual limits with the API owner."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["All JSON payloads in this guide are illustrative examples derived from the supplied specifications and published references. They are not real customer data and are not guaranteed production responses. All credentials are placeholders (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{{accessToken}}"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{{apiKey}}"]},") and must never be committed or logged. No API call was executed and no linting or validation tool was run in the course of producing this guide."]}]}]},"headings":[{"value":"Listening Query API V3 — Developer Guide","id":"listening-query-api-v3--developer-guide","depth":1},{"value":"1. Overview","id":"1-overview","depth":2},{"value":"1.1 The query model","id":"11-the-query-model","depth":3},{"value":"1.2 Prerequisite: Listening must be enabled","id":"12-prerequisite-listening-must-be-enabled","depth":3},{"value":"2. Base URLs and environments","id":"2-base-urls-and-environments","depth":2},{"value":"3. Authentication and common headers","id":"3-authentication-and-common-headers","depth":2},{"value":"4. POST /api/v3/listening/query/stream — Query Listening Stream","id":"4-post-apiv3listeningquerystream--query-listening-stream","depth":2},{"value":"4.1 Volume limits","id":"41-volume-limits","depth":3},{"value":"4.2 Request body","id":"42-request-body","depth":3},{"value":"4.3 The details object (stream)","id":"43-the-details-object-stream","depth":3},{"value":"4.4 The filters[] array","id":"44-the-filters-array","depth":3},{"value":"4.5 Example request","id":"45-example-request","depth":3},{"value":"4.6 Example response","id":"46-example-response","depth":3},{"value":"4.7 Response envelope","id":"47-response-envelope","depth":3},{"value":"4.8 Message object — data.result[]","id":"48-message-object--dataresult","depth":3},{"value":"apiStatus and empty content","id":"apistatus-and-empty-content","depth":4},{"value":"5. POST /api/v3/listening/query/widget — Query Listening Widget","id":"5-post-apiv3listeningquerywidget--query-listening-widget","depth":2},{"value":"5.1 Request body","id":"51-request-body","depth":3},{"value":"5.2 The details object (widget)","id":"52-the-details-object-widget","depth":3},{"value":"Which fields each widgetType needs","id":"which-fields-each-widgettype-needs","depth":4},{"value":"5.3 Example request","id":"53-example-request","depth":3},{"value":"5.4 Example response","id":"54-example-response","depth":3},{"value":"5.5 Response parameters","id":"55-response-parameters","depth":3},{"value":"6. Response format and status codes","id":"6-response-format-and-status-codes","depth":2},{"value":"6.1 Envelopes at a glance","id":"61-envelopes-at-a-glance","depth":3},{"value":"6.2 The errors array","id":"62-the-errors-array","depth":3},{"value":"6.3 Response codes","id":"63-response-codes","depth":3},{"value":"7. V2 → V3 migration","id":"7-v2--v3-migration","depth":2},{"value":"7.1 The headline: almost nothing changes","id":"71-the-headline-almost-nothing-changes","depth":3},{"value":"7.2 Endpoint mapping","id":"72-endpoint-mapping","depth":3},{"value":"8. Dimensions, metrics, and widget types — reference","id":"8-dimensions-metrics-and-widget-types--reference","depth":2},{"value":"9. Use cases","id":"9-use-cases","depth":2},{"value":"9.1 Replace client-side counting with a distribution widget","id":"91-replace-client-side-counting-with-a-distribution-widget","depth":3},{"value":"9.2 Export a full day of mentions safely","id":"92-export-a-full-day-of-mentions-safely","depth":3},{"value":"9.3 Idempotent incremental sync","id":"93-idempotent-incremental-sync","depth":3},{"value":"9.4 Build a sentiment-by-channel matrix","id":"94-build-a-sentiment-by-channel-matrix","depth":3},{"value":"9.5 Plot a volume trend","id":"95-plot-a-volume-trend","depth":3},{"value":"9.6 Exclude a noisy sub-topic","id":"96-exclude-a-noisy-sub-topic","depth":3},{"value":"9.7 Strip markup before indexing message text","id":"97-strip-markup-before-indexing-message-text","depth":3},{"value":"9.8 Reconcile \"the API returns empty text\"","id":"98-reconcile-the-api-returns-empty-text","depth":3},{"value":"10. Caveats and best practices","id":"10-caveats-and-best-practices","depth":2}],"frontmatter":{"seo":{"title":"Listening Query API V3 — Developer Guide"}},"lastModified":"2026-10-12T13:41:43.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/developer-guides-v3/listening-api-v3-developer-guide","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}