Skip to main content

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.

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: Create a Social Listening topic

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"
}
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. 
POST https://listening.dashsocial.com/organizations/{organization_id}/stats
body = {
    "topic_id": 4502,
    "search_filters": {
        "source_created": {
            "on_or_after": "2025-04-04T00:00:00",
            "on_or_before": "2025-05-01T23:59:59"
        }
    },
    "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": {
        "total_posts": 2986,
        "total_engagements": 290838,
        "average_engagements_per_post": 97,
        "unique_creators": 1659
    }
}

​
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": 4502,
    "filters": {
        "keywords_and_hashtags": "((elf) 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": [
        {
            "source_id": "18252971833210580",
            "caption": "Hoje com o meu parceiro ❤️",
            "permalink": "https://www.instagram.com/p/C3pZIwMt6WH/",
            "source": "INSTAGRAM",
            "source_created_at": "2024-02-22T10:40:39",
            "source_creator_handle": "cristiano",
            "source_creator_avatar": "https://cdn.dashsocial.com/avatars/173560420.jpeg",
            "media_type": "IMAGE",
            "post_type": "CAROUSEL",
            "engagements": 21559380,
            "likes": 21414308,
            "comments": 145072,
            "engagement_rate": 0.0346,
            "sentiment": {
                "is_positive": true,
                "is_neutral": false,
                "is_negative": false,
                "is_question": false
            },
            "urls": {
                "full": "https://cdn.dashsocial.com/media/full/1708612533.052381361527.jpeg"
            }
        }
    ]
}
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": 4502,
    "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: 
{
    "data": {
        "2025-04-04 00:00:00": {
            "count": 161,
            "breakdown": {
                "type": "SENTIMENT",
                "data": [
                    {
                        "group": "positive",
                        "count": 78
                    },
                    {
                        "group": "neutral",
                        "count": 81
                    },
                    {
                        "group": "negative",
                        "count": 2
                    }
                ]
            }
        },
        "2025-04-05 00:00:00": {
            "count": 107,
            "breakdown": {
                "type": "SENTIMENT",
                "data": [
                    {
                        "group": "positive",
                        "count": 66
                    },
                    {
                        "group": "neutral",
                        "count": 41
                    },
                    {
                        "group": "negative",
                        "count": 0
                    }
                ]
            }
        }
    }
}

​
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 = {
    "topic_id": 4502,
    "search_filters": {
        "source_created": {
            "on_or_after": "2025-04-04T00:00:00",
            "on_or_before": "2025-05-01T23:59:59"
        }
    },
    "include_keywords": true,
    "include_hashtags": 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": [
        {
            "keyword": "cosmetics",
            "count": 3086,
            "field": "keywords",
            "sentiment": {
                "positive": 1952,
                "neutral": 1088,
                "negative": 46
            }
        },
        {
            "keyword": "lip",
            "count": 1246,
            "field": "keywords",
            "sentiment": {
                "positive": 844,
                "neutral": 402,
                "negative": 0
            }
        },
        {
            "keyword": "new release 2025 cosmetics",
            "count": 857,
            "field": "keywords",
            "sentiment": {
                "positive": 567,
                "neutral": 290,
                "negative": 0
            }
        }
    ]
}

​
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": "e.l.f. Cosmetics and Skincare (@elfcosmetics) • Instagram photos ...",
            "url": "https://www.instagram.com/elfcosmetics/?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": "e.l.f. - Wikipedia",
            "url": "https://en.wikipedia.org/wiki/E.l.f.",
            "snippet": "7 days ago ... e.l.f. Beauty, Inc. is an American cosmetics brand based in Oakland, California. It was founded by Joseph Shamah and Scott Vincent Borba 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

​
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 a specific 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": {
        "id": 4502,
        "name": "ELF",
        "audience_type": "PUBLIC",
        "selected_brand_id": 4688,
        "paused": false,
        "search_body": {
            "filters": {
                "keywords_and_hashtags": "((elf) AND (cosmetics))",
                "source_created": {
                    "on_or_after": "2025-07-04T00:00:00",
                    "on_or_before": "2025-07-31T23:59:59",
                    "rolling_date_range_offset": 27
                },
                "sources": [
                    "FACEBOOK",
                    "INSTAGRAM",
                    "LINKEDIN",
                    "REDDIT",
                    "TIKTOK",
                    "TWITTER",
                    "WEB",
                    "YOUTUBE"
                ],
                "websearch": {
                    "enabled": true
                }
            }
        },
        "created_at": "2024-04-03 14:59:40",
        "updated_at": "2025-07-31 16:10:57"
    }
}