Monitor brand mentions with 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.

Campaign Monitoring

Track mentions and sentiment during product launches to measure audience reaction

Competitor Intelligence

Identify which topics and hashtags are trending in your industry

UGC Discovery

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. If you don’t have your organization ID, call GET https://auth.dashsocial.com/api/self using your API key:

curl 'https://auth.dashsocial.com/api/self' \
  -H 'Authorization: Bearer {token}'

Sample response:

{
    "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.

GET https://listening.dashsocial.com/organizations/{organization_id}/topics/{topic_id}

Key query parameters

topic_id: Topic to retrieve

Sample Response:

{
    "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.

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:

{
    "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.

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:

{
    "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.

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:

{
    "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.

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:

{
    "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.

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:

{
    "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 topic to define which conversations to track. Set keyword filters, date ranges, and platforms.

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:

{
    "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.

GET https://listening.dashsocial.com/organizations/{organization_id}/topics

Sample Response:

{
    "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"
        }
    ]
}

Get Started

Reporting

Campaigns

Scheduler

Social Commerce

Social Listening

Community

Integration

MCP Server

Monitor brand mentions with the Social Listening API

Use cases

Campaign Monitoring

Competitor Intelligence

UGC Discovery

Before you start

Implementation

Step 1: Get an existing topic

Key query parameters

Step 2: Get topic summary statistics

Key body parameters

Step 3: Retrieve top performing posts

Key body parameters

Step 4: Track daily mentions by sentiment, platform, or media type

Key body parameters

Step 5: Get top keywords and hashtags

Key body parameters

Step 6: Get top web results

Key query parameters

Additional operations

Key body parameters

Get all topics

​Use cases

Campaign Monitoring

Competitor Intelligence

UGC Discovery

​Before you start

​Implementation

​Step 1: Get an existing topic

​Key query parameters

​Step 2: Get topic summary statistics

​Key body parameters

​Step 3: Retrieve top performing posts

​Key body parameters

​Step 4: Track daily mentions by sentiment, platform, or media type

​Key body parameters

​Step 5: Get top keywords and hashtags

​Key body parameters

​Step 6: Get top web results

​Key query parameters

​Additional operations

​Create a Social Listening topic

​Key body parameters

​Get all topics

Use cases

Before you start

Implementation

Step 1: Get an existing topic

Key query parameters

Step 2: Get topic summary statistics

Key body parameters

Step 3: Retrieve top performing posts

Key body parameters

Step 4: Track daily mentions by sentiment, platform, or media type

Key body parameters

Step 5: Get top keywords and hashtags

Key body parameters

Step 6: Get top web results

Key query parameters

Additional operations

Create a Social Listening topic

Key body parameters

Get all topics