> ## Documentation Index
> Fetch the complete documentation index at: https://developer.dashsocial.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Monitor brand mentions with the Social Listening API
> Track conversations, monitor sentiment, and discover UGC using the Social Listening API.
Want to understand what people are saying about your brand across platforms? This guide shows you how to monitor conversations, track sentiment shifts, and discover viral UGC using the Social Listening API. You'll set up keyword tracking and pull actionable insights to inform your marketing strategy.
## Use cases
Understanding audience reaction to campaigns in real time is difficult when conversations happen across platforms. Social Listening surfaces trending topics, measures sentiment shifts, and discovers high-performing UGC.
Track mentions and sentiment during product launches to measure audience reaction
Identify which topics and hashtags are trending in your industry
Find top-performing creator content mentioning your brand or products
## Before you start
Make sure you have:
* **API Key** - Your authentication token
* **Organization ID** - Your org's unique identifier
* **Brand ID** - The brand you want to track mentions for
If you need help getting these, check out our [API Quickstart](https://developer.dashsocial.com/guides/get-started/quickstart).
If you don't have your organization ID, call `GET https://auth.dashsocial.com/api/self` using your API key:
```bash theme={null} theme={null}
curl 'https://auth.dashsocial.com/api/self' \
-H 'Authorization: Bearer {token}'
```
Sample response:
```json theme={null} theme={null}
{
"accessible_brands": [144],
"brands": {
"your-brand": {
"id": 144,
"name": "Your Brand",
"organization": {
"id": 1,
"name": "Your Organization"
},
"organization_id": 1
}
},
"organization": {
"id": 1,
"name": "Your Organization"
},
"organization_id": 1
}
```
Look for `organization_id` at the top level of the response.
## Implementation
### Step 1: Get an existing topic
Retrieve detailed information about a single topic, including all filter settings.
```http theme={null}
GET https://listening.dashsocial.com/organizations/{organization_id}/topics/{topic_id}
```
#### Key query parameters
* `topic_id`: Topic to retrieve
Sample Response:
```json theme={null}
{
"data": {
"created_at": "2025-07-22 14:38:16",
"filters_last_updated_at": "2025-07-23 20:26:31",
"id": 14788,
"image_data": [],
"keywords_and_hashtags_updated_at": "2025-07-23 20:26:31",
"mentions_last_refreshed_at": "2025-07-23 20:26:35",
"meta": {
"image_keyword_map": [],
"image_keywords_expression": "",
"keyword_and_hashtags_editor_text": "(cosmetics OR new release 2025)"
},
"name": "Cosmetics 2025",
"paused": false,
"refresh_frequency": "STANDARD",
"search_body": {
"filters": {
"keywords_and_hashtags": "(cosmetics OR new release 2025)",
"source_created": {
"rolling_date_range_offset": 27
},
"sources": [
"FACEBOOK",
"INSTAGRAM",
"LINKEDIN",
"REDDIT",
"TIKTOK",
"TWITTER",
"WEB",
"YOUTUBE"
]
},
"sorts": []
},
"selected_brand_id": 4688,
"updated_at": "2025-07-23 20:26:35",
"visual": false
}
}
```
Save the `id` value. This is your `topic_id` for all subsequent requests.
### Step 2: Get topic summary statistics
Pull post volume, total engagements, and unique creators for a quick view of conversation size and reach.
The Social Listening API requires you to include the `filters` object from Step 1's topic response in subsequent API calls. Some endpoints use `search_filters` as the parameter name (e.g., `/stats`, `/top_keywords`), while others use `filters` (e.g., `/search`, `/time_series`). This ensures your queries stay scoped to the topic's configured keywords and sources.
```http theme={null}
POST https://listening.dashsocial.com/organizations/{organization_id}/stats
body = {
"topic_id": 14788,
"search_filters": {
"keywords_and_hashtags": "((new release 2025) AND (cosmetics))",
"source_created": {
"on_or_after": "2025-04-04T00:00:00",
"on_or_before": "2025-05-01T23:59:59"
},
"sources": [
"FACEBOOK",
"INSTAGRAM",
"LINKEDIN",
"REDDIT",
"TIKTOK",
"TWITTER",
"WEB",
"YOUTUBE"
]
},
"use_estimates": true
}
```
#### Key body parameters
* `topic_id`: Topic ID from Step 1
* `search_filters.source_created`: Date range for posts to include
* `use_estimates`: Set to `true` for accurate results. Uses a mix of estimated and actual counts
Sample Response:
```json theme={null}
{
"data": {
"average_engagements_per_post": 442,
"average_impressions_per_post": 4980,
"negative_sentiment": 336,
"net_sentiment": 63,
"neutral_sentiment": 3003,
"positive_sentiment": 6533,
"total_engagements": 4364255,
"total_impressions": 49134857,
"total_posts": 9867
}
}
```
### Step 3: Retrieve top performing posts
Find the highest-engagement posts to identify viral UGC or influencer content worth resharing.
```http theme={null}
POST https://listening.dashsocial.com/organizations/{organization_id}/search
body = {
"topic_id": 14788,
"filters": {
"keywords_and_hashtags": "((new release 2025) AND (cosmetics))",
"source_created": {
"on_or_after": "2025-07-04T00:00:00",
"on_or_before": "2025-07-31T23:59:59"
},
"sources": [
"FACEBOOK",
"INSTAGRAM",
"LINKEDIN",
"REDDIT",
"TIKTOK",
"TWITTER",
"WEB",
"YOUTUBE"
]
},
"sorts": [
"-engagements",
"-date"
],
"paging": {
"limit": 50,
"offset": 0
}
}
```
#### Key body parameters
* `topic_id`: Topic ID from Step 1
* `filters.keywords_and_hashtags`: Refine keyword search within the topic
* `filters.source_created`: Date range for posts to include
* `filters.sources`: Platforms to include. Omit to search all platforms
* `sorts`: Sort order. Use `-engagements` for highest engagement first, `-date` for most recent
* `paging.limit`: Posts per request (max 50)
* `paging.offset`: Pagination offset for subsequent pages
Sample Response:
```json theme={null}
{
"data": [
{
"caption": "Just tried the new lipstick from this brand and honestly obsessed. The color payoff is unreal.",
"media_type": "IMAGE",
"mention_type": "CAPTION",
"engagements": 12,
"impressions": 241,
"likes": 11,
"retweets": 1,
"quote_tweets": 0,
"replies": 0,
"sentiment": {
"is_negative": false,
"is_neutral": true,
"is_positive": false,
"is_question": true
},
"source": "TWITTER",
"source_created_at": "2025-08-15T00:44:25",
"source_creator_handle": "sample_user",
"source_creator_id": "15044945",
"source_id": "1956154979112124489",
"permalink": "https://twitter.com/15044945/status/1956154979112124489",
"creator_location_country": "United States",
"import_event_origin": "TWITTER_SEARCH",
"image_url": "https://cdn.dashsocial.com/twitter/image/sample-image.jpg"
}
]
}
```
**Pagination tip:** Increment `offset` by your `limit` value to get more results (e.g., offset 0, 50, 100).
### Step 4: Track daily mentions by sentiment, platform, or media type
Break down post volume over time to spot trends. Group by sentiment to measure brand perception. Group by platform to see where conversations happen.
```http theme={null}
POST https://listening.dashsocial.com/organizations/{organization_id}/time_series/post_volume
body = {
"topic_id": 14788,
"breakdown_by": "SENTIMENT",
"scale": "DAY",
"filters": {
"source_created": {
"on_or_after": "2025-04-04T00:00:00",
"on_or_before": "2025-04-08T23:59:59"
}
}
}
```
#### Key body parameters
* `topic_id`: Topic ID from Step 1
* `breakdown_by`: How to group results. Options: `CREATOR`, `INDUSTRY`, `PLATFORM`, `MEDIA_TYPE`, `SENTIMENT`
* `scale`: Time interval for results. Use `DAY` for daily breakdown
* `filters.source_created`: Date range for posts to include
Sample Response:
```json theme={null}
{
"count": 6,
"data": {
"2025-06-13 00:00:00": {
"breakdown": {
"data": [
{
"count": 2,
"group": "negative",
"metadata": {
"es_posts_count": 2,
"total_posts_count": 2
}
},
{
"count": 0,
"group": "neutral",
"metadata": {
"es_posts_count": 0,
"total_posts_count": 0
}
},
{
"count": 1,
"group": "positive",
"metadata": {
"es_posts_count": 1,
"total_posts_count": 1
}
}
],
"type": "SENTIMENT"
},
"count": 3,
"metadata": {
"es_posts_count": 3,
"total_posts_count": 3
}
}
},
"metadata": {
"es_posts_count": 6,
"total_posts_count": 6
}
}
```
### Step 5: Get top keywords and hashtags
Discover the most frequent keywords and hashtags in your topic. Use this to identify trending themes and refine future campaigns.
```http theme={null}
POST https://listening.dashsocial.com/organizations/{organization_id}/top_keywords
body = {
"search_filters": {
"keywords_and_hashtags": "((new release 2025) AND (cosmetics))",
"source_created": {
"on_or_after": "2025-06-26T00:00:00",
"on_or_before": "2025-07-23T23:59:59",
"rolling_date_range_offset": 27
}
},
"topic_id": 14788,
"include_keywords": true,
"include_hashtags": true,
"use_estimates": true
}
```
#### Key body parameters
* `topic_id`: Topic ID from Step 1
* `search_filters.source_created`: Date range for posts to include
* `include_keywords`: Set to `true` to include top keywords
* `include_hashtags`: Set to `true` to include top hashtags
Sample Response:
```json theme={null}
{
"data": [
{
"count": 1342,
"field": "hashtags",
"keyword": "#glossier",
"sentiment": {
"negative": 18,
"neutral": 240,
"positive": 1084
}
},
{
"count": 2123,
"field": "keywords",
"keyword": "lip",
"sentiment": {
"negative": 82,
"neutral": 798,
"positive": 1243
}
},
{
"count": 2300,
"field": "keywords",
"keyword": "beauty",
"sentiment": {
"negative": 73,
"neutral": 730,
"positive": 1497
}
}
]
}
```
### Step 6: Get top web results
Retrieve non-social web content like news articles, blog posts, or press releases mentioning your topic.
```http theme={null}
GET https://listening.dashsocial.com/organizations/{organization_id}/topics/{topic_id}/websearch_results?limit=24
```
#### Key query parameters
* `topic_id`: Topic ID from Step 1
* `limit`: Web results to return
Sample Response:
```json theme={null}
{
"data": [
{
"name": "Cosmetics and Skincare • Instagram photos ...",
"url": "https://www.instagram.com/cosmetics/?hl=en",
"snippet": "2 days ago ... 7M Followers, 1325 Following, 11K Posts - e.l.f. Cosmetics and Skincare (@elfcosmetics) on Instagram: \"Welcome to the beauty-verse: where every EYE 👁️ LIP ...",
"created_at": "2025-03-17 20:33:56",
"updated_at": "2025-05-02 12:17:18"
},
{
"name": "Cosmetics - Wikipedia",
"url": "https://en.wikipedia.org/wiki/Cosmetics",
"snippet": "7 days ago ... Cosmetics Beauty, Inc. is an American cosmetics brand based in Example, California. It was founded in 2004.",
"created_at": "2025-03-17 20:33:56",
"updated_at": "2025-05-02 12:17:18"
}
],
"paging": {
"limit": 24,
"offset": 0
}
}
```
## Additional operations
### Create a Social Listening topic
Create a topic to define which conversations to track. Set keyword filters, date ranges, and platforms.
```http theme={null}
POST https://listening.dashsocial.com/organizations/{organization_id}/topics
body = {
"name": "New cosmetic release 2025",
"audience_type": "PUBLIC",
"selected_brand_id": {brand_id},
"search_body": {
"filters": {
"keywords_and_hashtags": "((new release 2025) AND (cosmetics))",
"source_created": {
"rolling_date_range_offset": 27
}
}
}
}
```
#### Key body parameters
* `name`: Topic name for your team to identify it
* `audience_type`: Audience scope. Use `PUBLIC` for publicly available content
* `selected_brand_id`: Brand ID whose competitor list you want to track
* `search_body.filters.keywords_and_hashtags`: Keywords or hashtags to track. Use boolean operators like AND, OR, NOT
* `source_created.rolling_date_range_offset`: Days back from today (e.g., 27 = last 28 days including today)
Sample Response:
```json theme={null}
{
"id": 4502,
"name": "New cosmetic release 2025",
"audience_type": "PUBLIC",
"selected_brand_id": 4688,
"search_body": {
"filters": {
"keywords_and_hashtags": "((new release 2025) AND (cosmetics))",
"source_created": {
"rolling_date_range_offset": 27
}
}
},
"created_at": "2025-01-26T14:59:40+00:00"
}
```
### Get all topics
List all Social Listening topics your organization is tracking.
```http theme={null}
GET https://listening.dashsocial.com/organizations/{organization_id}/topics
```
Sample Response:
```json theme={null}
{
"data": [
{
"id": 4502,
"name": "ELF",
"audience_type": "PUBLIC",
"selected_brand_id": 4688,
"paused": false,
"mentions_used": 55,
"mentions_last_refreshed_at": "2025-05-01 20:00:12",
"created_at": "2024-04-03 14:59:40"
},
{
"id": 6070,
"name": "National Sanitation Foundation",
"audience_type": "PUBLIC",
"paused": false,
"mentions_used": 11,
"mentions_last_refreshed_at": "2025-05-01 20:00:13",
"created_at": "2024-09-06 13:43:24"
}
]
}
```