> ## 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 top UGC posts with content report > Identify and rank top-performing user-generated content posts by engagement metrics. Measure the impact of user-generated content and creator posts that mention your brand. Pull total performance metrics for brand mentions across Instagram and TikTok to quantify your UGC value. *** ## Use cases Measuring UGC impact across platforms is hard when data is scattered. Metric reports give you total performance numbers for all brand mentions in one request. Measure total reach and engagement from influencer content to calculate partnership value and justify budgets Pull total comments, likes, and shares during campaign periods to measure impact and report to stakeholders Benchmark UGC engagement across Instagram, Stories, and TikTok to optimize your content strategy *** ## Before you start Make sure you have: * **API Key** - Your authentication token from Dash Social developer settings * **Brand ID** - The ID for the brand you want to track UGC mentions for Need help? Check out our [API Quickstart](https://developer.dashsocial.com/guides/get-started/quickstart). **Supported platforms** This report supports these UGC channels: * Instagram: `INSTAGRAM_UGC` * Instagram Stories: `INSTAGRAM_STORIES_UGC` * TikTok: `TIKTOK_UGC` **About earned reports** Earned reports track user-generated content that mentions or tags your brand. Unlike Owned reports (content you published) or Competitor reports (content from competitors), Earned reports measure UGC performance. **Test in the UI first:** Create a Dashboard in the Dash Social UI and configure your Earned report there. This previews the metrics and validates your filters before writing code. **One channel per request:** You cannot query multiple UGC channels in the same request. Make separate API calls for each channel. *** ## Implementation ### Step 1: Map your parameters Review the available parameters before making your API call:
Parameter Description
`brand_ids` Brand IDs from the UI. Separate multiple brands with commas (e.g., `144,145`)
`channels` UGC platforms to include: * Instagram: `INSTAGRAM_UGC` * Instagram Stories: `INSTAGRAM_STORIES_UGC` * TikTok: `TIKTOK_UGC` **Note:** Make separate API calls for each channel
`metrics` UGC metrics to return (e.g., `UGC_COMMENTS`, `UGC_LIKES`, `UGC_REACH`). See [Metrics section](#metrics) for available options per channel
`start_date` / `end_date` Reporting date range in `YYYY-MM-DD` format
`context_start_date` / `context_end_date` Comparison date range for trend analysis. Use same dates as `start_date` / `end_date` if no comparison needed
`report_type` Set to `CONTENT` for ranked post lists
`limit` Number of posts to return. Useful for "top performers" dashboards
*** ### Step 2: Make the API call Send a GET request using the parameters from Step 1. This example pulls the top Instagram UGC post ranked by organic comments from August 10-20, with July 1-31 as the comparison period. ```http theme={null} GET https://dashboard.dashsocial.com/reports/data ?channels=INSTAGRAM_UGC &brand_ids=144 &start_date=2025-08-10 &end_date=2025-08-20 &context_start_date=2024-07-01 &context_end_date=2024-07-31 &metrics=UGC_ORGANIC_COMMENTS &report_type=CONTENT &limit=1 ``` ### Multiple metrics Request multiple metrics in a single call by separating them with commas (e.g., `UGC_COMMENTS,UGC_LIKES,UGC_REACH`). **Date format matters:** Always use `YYYY-MM-DD` format for dates (e.g., `2025-08-10`). Other formats will cause errors. **One channel per request:** Make separate API calls for each channel (`INSTAGRAM_UGC`, `INSTAGRAM_STORIES_UGC`, `TIKTOK_UGC`). #### Sample response The API returns ranked posts with detailed performance metrics, creator information, and media URLs. Posts are automatically ranked by the metric you selected. ```json theme={null} { "data": { "144": { "avatar": "https://cdn.dashsocial.com/avatars/2306810931.jpeg", "data_type": "BRAND", "name": "sunny.today", "user_has_access": true }, "content": [ { "brand_id": 144, "brand_media_id": 873293370, "creator": { "avatar_url": "https://cdn.dashsocial.com/avatars/46010677878.jpeg", "handle": "pat_chisholm_tester_" }, "instagram": { "caption": "@sunny.today", "comments_count": 1, "effectiveness": 0.5, "emv": 308.359, "engagement": 0.6666666666666666, "like_count": 1, "reach": 4, "saved": 0, "shares": 0, "sum_total_engagements": 2, "timestamp": "2025-08-20T18:09:06+00:00", "total_comments": 1, "total_likes": 1, "url": "https://www.instagram.com/p/DNlhsFyunKl/", "views": 62 }, "source": "INSTAGRAM", "source_created_at": "2025-08-20T18:09:06", "source_type": "UGC", "type": "IMAGE" } ] }, "product_category": "UGC" } ``` **Understanding the response:** The response includes rich data for each UGC post: creator handle and avatar, direct link, caption, engagement metrics, reach, and EMV. In this example, creator `@pat_chisholm_tester_` mentioned brand `@sunny.today` in an Instagram post on August 20. The post received 1 comment, 1 like, and reached 4 unique accounts. *** ## Metrics | Metric Name | Description | Metric API Name | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | | UGC - Avg. EMV | The average earned media value of posts featuring you. EMV is calculated by factoring in the channel, audience size, content type, engagement and current market values for comparable posts. | `AVG_EMV` | | Total Social Impact - All Posts | TSI is like a market index for your brand's social presence - it brings together everything your brand does across social to reveal the strength of your total presence. It rolls up all your channels, content, and engagement into one score that grows over time, giving you a clear view of performance and momentum. | `TOTAL_TSI` | | UGC - Avg. Effectiveness | The average percentage of people who saw posts featuring you and engaged with them | `UGC_AVG_EFFECTIVENESS_CONNECTED` | | UGC - Avg. Effectiveness | The average percentage of people who saw posts featuring you and engaged with them. If connected creators are included in this report, their true reach and engagements will be used to calculate their Avg. Effectiveness. | `UGC_AVG_EFFECTIVENESS_PUBLIC` | | UGC - Avg. Engagement Rate (Followers) | The average percentage of people who engaged with posts featuring you, based on follower count. This metric uses Likes. If Likes are hidden on Instagram, they will show as 0 in Dash Social. If connected creators are included in this report, their true engagements will be used to calculate their engagement rate. | `UGC_AVG_ENGAGEMENT_RATE_FOLLOWERS` | | UGC - Avg. Engagement Rate (Views) | The average percentage of people who engaged with posts featuring you, based on the number of people who viewed it. This metric uses Likes. If Likes are hidden on Instagram, they will show as 0 in Dash Social. | `UGC_AVG_ENGAGEMENT_RATE_VIEWS` | | UGC - Avg. Estimated Reach | The estimated average number of unique accounts that saw posts featuring you. If connected creators are included in this report, their true reach is included with unconnected creators’ estimated reach. | `UGC_AVG_ESTIMATED_REACH` | | UGC - Avg. Reach | The average number of unique accounts that saw posts featuring you | `UGC_AVG_REACH` | | UGC - Avg. Watch Time | The average time that posts featuring you were played during a single viewing | `UGC_AVG_WATCH_TIME` | | UGC - Comments | The number of comments on posts featuring you | `UGC_COMMENTS` | | UGC - EMV | The earned media value of the creator's content. EMV is calculated by factoring in the channel, audience size, content type, engagement and current market values for comparable posts. | `UGC_EMV` | | UGC - Engagements | The total number of engagements on posts featuring you. If Likes are hidden on Instagram, they will show as 0 in Dash Social. | `UGC_ENGAGEMENTS_CONNECTED` | | UGC - Engagements | The total number of engagements on posts featuring you. If Likes are hidden on Instagram, they will show as 0 in Dash Social. If connected creators are included in this report, their true engagements is included with the unconnected creators' engagements. | `UGC_ENGAGEMENTS_PUBLIC` | | UGC - Estimated Reach | The estimated number of unique accounts who saw posts that mentioned or tagged you | `UGC_ESTIMATED_REACH` | | UGC - Followers Gained | The estimated number of followers your brand has gained from posts featuring you | `UGC_FOLLOWERS_GAINED` | | UGC - Likes | The number of likes received on posts featuring you | `UGC_LIKES` | | UGC - Mentions | The total number of times you were mentioned by other accounts by including your @username in their caption | `UGC_MENTIONS` | | UGC - Number of Posts | The total number of posts that mentioned or tagged you | `UGC_NUMBER_OF_POSTS` | | UGC - Photo Tags | The total number of times you were tagged by other accounts by using a photo tag on the post | `UGC_PHOTO_TAGS` | | UGC - Reach | The number of unique accounts who saw posts featuring you | `UGC_REACH` | | UGC - Saves | The number of times posts featuring you were saved | `UGC_SAVES` | | UGC - Shares | The number of times posts featuring you were shared | `UGC_SHARES` | | UGC - Time Watched | The amount of time videos featuring you were played during a single viewing | `UGC_TIME_WATCHED` | | UGC - Views | The amount of times videos featuring you were played or replayed for 1ms or more. Replays are counted after the initial play in the same video session. | `UGC_VIEWS` | | UGC - Views | The amount of times videos featuring you were played or replayed for 1ms or more. Replays are counted after the initial play in the same video session. | `UGC_VIEWS_PUBLIC` | | Metric Name | Description | Metric API Name | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | | Avg. Completion Rate | The average completion rate of story frames featuring you that were published during the reporting period. This metric is only available for reporting after March 24, 2025. | `AVG_COMPLETION_RATE` | | Avg. EMV | The average earned media value of the story frames featuring you. | `AVG_EMV` | | Avg. Exit Rate | The average exit rate of story frames featuring you that were published during the reporting period. This metric is only available for reporting after March 24, 2025. | `AVG_EXIT_RATE` | | Avg. Reach | The average number of unique accounts that saw posts featuring you | `AVG_REACH` | | Exits | The number of times a viewer has swiped out of the story or tapped the X in the upper-right corner of the story frame on stories featuring you. An exit is counted even if it occurs at the last millisecond. | `EXITS` | | Number of Story Frames | The number of stories featuring you | `NUMBER_OF_POSTS` | | Replies | The number of replies to stories featuring you | `REPLIES` | | Taps Back | The number of people who tapped backwards on stories featuring you | `TAPS_BACK` | | Taps Forward | The number of people who tapped forward on stories featuring you | `TAPS_FORWARD` | | EMV | The average earned media value of the story frames featuring you. EMV is calculated by factoring in the channel, audience size, content type, engagement and current market values for comparable posts. | `UGC_EMV` | | Views | The number of times that story frames featuring you were displayed on a person's screen. This includes repeat views. This metric is only available for reporting after March 24, 2025. | `VIEWS` | | Metric Name | Description | Metric API Name | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | | Avg. EMV | The average earned media value of posts featuring you. EMV is calculated by factoring in the channel, audience size, content type, engagement and current market values for comparable posts. | `AVG_EMV` | | Avg. Engagement Rate | The average percentage of people who engaged with posts featuring you, based on the number of people who viewed it | `AVG_ENGAGEMENT_RATE` | | Avg. Reach | The average number of unique accounts that saw posts featuring you | `AVG_REACH` | | Comments | The number of comments on posts featuring you | `COMMENTS` | | Shares | The number of times posts featuring you were shared | `SHARES` | | Total Social Impact - All Posts | TSI is like a market index for your brand's social presence - it brings together everything your brand does across social to reveal the strength of your total presence. It rolls up all your channels, content, and engagement into one score that grows over time, giving you a clear view of performance and momentum. | `TOTAL_TSI` | | EMV | The earned media value of the posts featuring you. EMV is calculated by factoring in the channel, audience size, content type, engagement and current market values for comparable posts. | `UGC_EMV` | | Likes | The number of likes received on posts featuring you | `UGC_LIKES` | | Number of Posts | The total number of posts featuring you | `UGC_NUMBER_OF_POSTS` | | Engagements | The total number of engagements received on posts featuring you | `UGC_TOTAL_ENGAGEMENTS` | | Video Views | The number of times videos featuring you were viewed. Replays are not counted. | `VIDEO_VIEWS` | ## Next steps You now have a JSON response with total UGC performance metrics per brand and platform. Use this data to: * **Calculate ROI** - Measure the value of creator partnerships and influencer campaigns * **Track campaigns** - Monitor UGC performance during specific campaign periods * **Compare platforms** - Analyze which channels drive the most UGC engagement **Related guides:** * [Visualize Earned Trends with Graph Report →](/guides/earned-graph-report) * [Get Top Earned Posts with Content Report →](/guides/earned-content-report) * [Compare Earned vs Owned Performance →](/guides/owned-report) * [View the Full API Reference →](https://developers.dashsocial.com/reference/get_reports-data)