> ## 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. # Get aggregated social listening metrics > Track aggregated social listening metrics across keyword-based topics. This guide shows you how to track aggregated social listening metrics using the Dash Social API. Pull totals and averages like total engagements, post volume, and unique creators to measure campaign impact and spot conversation trends. The Social Listening report provides aggregated metrics only. For full access to individual posts, top keywords, sentiment breakdowns, and web results, use the [Social Listening API](/guides/social-listening/monitor-brand-mentions-with-social-listening-api). ## Use cases Measuring campaign success across thousands of social listening posts is overwhelming. Metric reports aggregate this data instantly. Track total engagements and post volume to quantify your product launch reach Compare engagement rates week over week to identify when topics gain traction Show conversation health and brand mention trends with aggregated metrics Track how many unique creators discuss your brand over time ## Before you start You'll need: * **API Key** - Your authentication token * **Brand ID** - The ID of the brand you want to query Get help with these in our [API Quickstart](https://developer.dashsocial.com/guides/get-started/quickstart). ## Implementation ### Step 1: Get your topic ID Retrieve your topic ID to identify which conversation you want to analyze. ```http theme={null} GET https://listening.dashsocial.com/organizations/{organization_id}/topics ``` #### Key query parameters * `organization_id`: Your organization's unique ID If you don't have your organization ID, call `GET https://auth.dashsocial.com/api/self` using your API key: ```bash theme={null} curl 'https://auth.dashsocial.com/api/self' \ -H 'Authorization: Bearer {token}' ``` Sample response: ```json 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. Sample response: ```json theme={null} { "data": [ { "id": 11423, "name": "New cosmetic release 2025", "audience_type": "PUBLIC", "selected_brand_id": 144, "search_body": { "filters": { "keywords_and_hashtags": "((new release 2025) AND (cosmetics))" } } } ] } ``` **Already have a topic ID?** Skip to Step 2. **Need to create a topic?** See [Social Listening API: Monitor Mentions, Sentiment, and Trends](https://developer.dashsocial.com/docs/social-listening-api). ### Step 2: Map your parameters Review the available parameters before making your API call:
Parameter Description
`brand_ids` Your brand ID from the UI
`channels` Platform to query: * Instagram: `INSTAGRAM` * TikTok: `TIKTOK` * Facebook: `FACEBOOK` * YouTube: `YOUTUBE` * LinkedIn: `LINKEDIN` * X: `TWITTER` * Web: `WEB` * Reddit: `REDDIT`
`metrics` Social listening metrics available for all channels: * Avg. Engagements: `AVERAGE_ENGAGEMENTS_PER_POST` * Avg. Mentions: `AVG_MENTIONS_TOPIC` * Engagements: `TOTAL_ENGAGEMENTS_TOPIC` * Mentions: `TOTAL_MENTIONS_TOPIC` * Net Sentiment: `NET_SENTIMENT` See [Available Metrics](#available-metrics) for full descriptions. Request multiple metrics by separating with commas
`start_date` / `end_date` Reporting date range in YYYY-MM-DD format
`context_start_date` / `context_end_date` Comparison date range for period-over-period analysis. Optional
`report_type` Set to `TOTAL_METRIC` for aggregated totals
`listening.topic_ids` *(body)* Array of topic IDs from Step 1 (e.g., `[11423]`). Pass multiple IDs to query multiple topics at once
*** ### Step 3: Make the API call Send a PUT request using the parameters from Step 2 and the topic ID from Step 1. This example retrieves average engagements per post for topic `11423` on Instagram from May 1-7, with April 1-7 as the comparison period. ```http theme={null} PUT https://dashboard.dashsocial.com/reports/data ?channels=INSTAGRAM &brand_ids=144 &start_date=2025-05-01 &end_date=2025-05-07 &context_start_date=2025-04-01 &context_end_date=2025-04-07 &metrics=AVERAGE_ENGAGEMENTS_PER_POST &report_type=TOTAL_METRIC body = { "listening": { "topic_ids": [11423] } } ``` Sample response: ```json theme={null} { "data": { "144": { "avatar": "https://cdn.dashsocial.com/avatars/2306810931.jpeg", "data_type": "BRAND", "name": "sunny.today", "user_has_access": true }, "metrics": { "AVERAGE_ENGAGEMENTS_PER_POST": { "ALL_CHANNELS": { "context": 575, "context_change": -0.05391304347826087, "value": 544 } } } }, "product_category": "LISTENING" } ``` **Understanding the response:** The `value` field shows your reporting period total (544 average engagements). The `context` field shows your comparison period total (575). The `context_change` value of -0.054 indicates a 5.4% decrease. *** ## Metrics | Metric Name | Description | Metric API Name | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | | Avg. Engagements | The estimated average number of engagements per post within this Topic that were published during the reporting period | `AVERAGE_ENGAGEMENTS_PER_POST` | | Avg. Impressions | The estimated average number of impressions per post within this Topic during the reporting period. Impressions are estimated for Facebook, Instagram, X and Youtube. | `AVERAGE_IMPRESSIONS_PER_POST` | | Avg. Mentions | The estimated number of posts published per day within this Topic during the reporting period | `AVG_MENTIONS_TOPIC` | | Net Sentiment | The net sentiment of post captions within this Topic during the reporting period. Net sentiment shows the overall balance between positive and negative conversation. | `NET_SENTIMENT` | | Engagements | The estimated number of engagements on posts within this Topic that were published during the reporting period | `TOTAL_ENGAGEMENTS_TOPIC` | | Impressions | The estimated number of impressions on posts within this Topic during the reporting period. Impressions are estimated for Facebook, Instagram, X and Youtube. | `TOTAL_IMPRESSIONS_TOPIC` | | Mentions | The estimated number of posts published within this Topic during the reporting period | `TOTAL_MENTIONS_TOPIC` | | Metric Name | Description | Metric API Name | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | | Avg. Engagements | The estimated average number of engagements per post within this Topic that were published during the reporting period | `AVERAGE_ENGAGEMENTS_PER_POST` | | Avg. Mentions | The estimated number of posts published per day within this Topic during the reporting period | `AVG_MENTIONS_TOPIC` | | Net Sentiment | The net sentiment of post captions within this Topic during the reporting period. Net sentiment shows the overall balance between positive and negative conversation. | `NET_SENTIMENT` | | Engagements | The estimated number of engagements on posts within this Topic that were published during the reporting period | `TOTAL_ENGAGEMENTS_TOPIC` | | Mentions | The estimated number of posts published within this Topic during the reporting period | `TOTAL_MENTIONS_TOPIC` | | Metric Name | Description | Metric API Name | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | | Avg. Engagements | The estimated average number of engagements per post within this Topic that were published during the reporting period | `AVERAGE_ENGAGEMENTS_PER_POST` | | Avg. Impressions | The estimated average number of impressions per post within this Topic during the reporting period. Impressions are estimated for Facebook, Instagram, X and Youtube. | `AVERAGE_IMPRESSIONS_PER_POST` | | Avg. Mentions | The estimated number of posts published per day within this Topic during the reporting period | `AVG_MENTIONS_TOPIC` | | Net Sentiment | The net sentiment of post captions within this Topic during the reporting period. Net sentiment shows the overall balance between positive and negative conversation. | `NET_SENTIMENT` | | Engagements | The estimated number of engagements on posts within this Topic that were published during the reporting period | `TOTAL_ENGAGEMENTS_TOPIC` | | Impressions | The estimated number of impressions on posts within this Topic during the reporting period. Impressions are estimated for Facebook, Instagram, X and Youtube. | `TOTAL_IMPRESSIONS_TOPIC` | | Mentions | The estimated number of posts published within this Topic during the reporting period | `TOTAL_MENTIONS_TOPIC` | | Metric Name | Description | Metric API Name | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | | Avg. Engagements | The estimated average number of engagements per post within this Topic that were published during the reporting period | `AVERAGE_ENGAGEMENTS_PER_POST` | | Avg. Impressions | The estimated average number of impressions per post within this Topic during the reporting period. Impressions are estimated for Facebook, Instagram, X and Youtube. | `AVERAGE_IMPRESSIONS_PER_POST` | | Avg. Mentions | The estimated number of posts published per day within this Topic during the reporting period | `AVG_MENTIONS_TOPIC` | | Net Sentiment | The net sentiment of post captions within this Topic during the reporting period. Net sentiment shows the overall balance between positive and negative conversation. | `NET_SENTIMENT` | | Engagements | The estimated number of engagements on posts within this Topic that were published during the reporting period | `TOTAL_ENGAGEMENTS_TOPIC` | | Impressions | The estimated number of impressions on posts within this Topic during the reporting period. Impressions are estimated for Facebook, Instagram, X and Youtube. | `TOTAL_IMPRESSIONS_TOPIC` | | Mentions | The estimated number of posts published within this Topic during the reporting period | `TOTAL_MENTIONS_TOPIC` | | Metric Name | Description | Metric API Name | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | | Avg. Engagements | The estimated average number of engagements per post within this Topic that were published during the reporting period | `AVERAGE_ENGAGEMENTS_PER_POST` | | Avg. Mentions | The estimated number of posts published per day within this Topic during the reporting period | `AVG_MENTIONS_TOPIC` | | Net Sentiment | The net sentiment of post captions within this Topic during the reporting period. Net sentiment shows the overall balance between positive and negative conversation. | `NET_SENTIMENT` | | Engagements | The estimated number of engagements on posts within this Topic that were published during the reporting period | `TOTAL_ENGAGEMENTS_TOPIC` | | Mentions | The estimated number of posts published within this Topic during the reporting period | `TOTAL_MENTIONS_TOPIC` | | Metric Name | Description | Metric API Name | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | | Avg. Engagements | The estimated average number of engagements per post within this Topic that were published during the reporting period | `AVERAGE_ENGAGEMENTS_PER_POST` | | Avg. Impressions | The estimated average number of impressions per post within this Topic during the reporting period. Impressions are estimated for Facebook, Instagram, X and Youtube. | `AVERAGE_IMPRESSIONS_PER_POST` | | Avg. Mentions | The estimated number of posts published per day within this Topic during the reporting period | `AVG_MENTIONS_TOPIC` | | Net Sentiment | The net sentiment of post captions within this Topic during the reporting period. Net sentiment shows the overall balance between positive and negative conversation. | `NET_SENTIMENT` | | Engagements | The estimated number of engagements on posts within this Topic that were published during the reporting period | `TOTAL_ENGAGEMENTS_TOPIC` | | Impressions | The estimated number of impressions on posts within this Topic during the reporting period. Impressions are estimated for Facebook, Instagram, X and Youtube. | `TOTAL_IMPRESSIONS_TOPIC` | | Mentions | The estimated number of posts published within this Topic during the reporting period | `TOTAL_MENTIONS_TOPIC` | | Metric Name | Description | Metric API Name | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | | Avg. Engagements | The estimated average number of engagements per post within this Topic that were published during the reporting period | `AVERAGE_ENGAGEMENTS_PER_POST` | | Avg. Mentions | The estimated number of posts published per day within this Topic during the reporting period | `AVG_MENTIONS_TOPIC` | | Net Sentiment | The net sentiment of post captions within this Topic during the reporting period. Net sentiment shows the overall balance between positive and negative conversation. | `NET_SENTIMENT` | | Engagements | The estimated number of engagements on posts within this Topic that were published during the reporting period | `TOTAL_ENGAGEMENTS_TOPIC` | | Mentions | The estimated number of posts published within this Topic during the reporting period | `TOTAL_MENTIONS_TOPIC` | | Metric Name | Description | Metric API Name | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | | Avg. Engagements | The estimated average number of engagements per post within this Topic that were published during the reporting period | `AVERAGE_ENGAGEMENTS_PER_POST` | | Avg. Mentions | The estimated number of posts published per day within this Topic during the reporting period | `AVG_MENTIONS_TOPIC` | | Net Sentiment | The net sentiment of post captions within this Topic during the reporting period. Net sentiment shows the overall balance between positive and negative conversation. | `NET_SENTIMENT` | | Engagements | The estimated number of engagements on posts within this Topic that were published during the reporting period | `TOTAL_ENGAGEMENTS_TOPIC` | | Mentions | The estimated number of posts published within this Topic during the reporting period | `TOTAL_MENTIONS_TOPIC` | ## Next steps Use your metric data to: * **Track trends** - Query the same metrics weekly or monthly to spot momentum changes * **Build dashboards** - Create executive-friendly performance views with aggregated numbers * **Analyze sentiment** - Combine with the [Social Listening API](https://developer.dashsocial.com/docs/social-listening-api) to see sentiment shifts alongside engagement **Data freshness:** Metric updates vary by post age. Recently published posts refresh more frequently than older content. Focus on data from the last 90 days for the most accurate reporting. **Other social listening reports:** This guide covers metric reports. Social listening also supports graph reports (time-series data) and content reports (individual post data).