# Get assignees Source: https://developer.dashsocial.com/api-reference/community/community-interactions/get-assignees api-reference/community-openapi.json GET /assignees Returns a list of assignee users for the specified brands. Requires multi-brand inbox permission when querying multiple brands. # Get community interactions Source: https://developer.dashsocial.com/api-reference/community/community-interactions/get-community-interactions api-reference/community-openapi.json GET /community_interactions Gets the community interactions for a brand, and supports filtering. # List messages in a conversation interaction Source: https://developer.dashsocial.com/api-reference/community/community-interactions/get-interaction-messages api-reference/community-openapi.json GET /interaction/{conversation_id}/messages Get a paginated list of messages in community interaction that match given conversation ID # Get sentiment distribution stats Source: https://developer.dashsocial.com/api-reference/community/community-overview-v2/create-sentiment-distribution-stats api-reference/community-openapi.json POST /sentiment_distribution_stats Returns sentiment distribution stats for a brand. Supports filtering by date range, platform, and interaction type. # Get sentiment time series Source: https://developer.dashsocial.com/api-reference/community/community-overview-v2/create-sentiment-time-series api-reference/community-openapi.json POST /sentiment_time_series Returns per-platform sentiment time series data for a brand. Supports filtering by date range and interaction type. # Get top keywords Source: https://developer.dashsocial.com/api-reference/community/community-overview-v2/create-top-keywords api-reference/community-openapi.json POST /top_keywords Returns the top keywords from community interactions matching the provided filters, ranked by frequency. # Get volume time series Source: https://developer.dashsocial.com/api-reference/community/community-overview-v2/create-volume-time-series api-reference/community-openapi.json POST /volume_time_series Returns community interaction volume as a time series, broken down by interaction type (comments, messages, mentions, retweets, etc.) per date. Supports multiple brands, date range filtering, and interaction type filtering. # Get community overview stats Source: https://developer.dashsocial.com/api-reference/community/community-overview-v2/get-overview-stats api-reference/community-openapi.json GET /overview_stats Returns aggregated community overview header stats for the specified brands. Supports filtering by date range, platform, and interaction type. # Get a list of facebook comments Source: https://developer.dashsocial.com/api-reference/community/facebook-comments/get-facebook-comments api-reference/community-openapi.json GET /facebook_comments Get a paginated list of all comments made on a post # Get a comment Source: https://developer.dashsocial.com/api-reference/community/facebook-comments/get-facebook-comments-1 api-reference/community-openapi.json GET /facebook_comments/{community_interaction_id} Get a single comment by given parameters # List messages in a conversation Source: https://developer.dashsocial.com/api-reference/community/facebook-messages/get-facebook-messages api-reference/community-openapi.json GET /conversations/facebook/{conversation_id}/messages Get a paginated list of messages sorted chronologically most recent first. # Get list of comments on media object Source: https://developer.dashsocial.com/api-reference/community/instagram-comments/get-instagram-comments api-reference/community-openapi.json GET /instagram_comments Get paginated result of all comments on media object with nested replies # Get a comment Source: https://developer.dashsocial.com/api-reference/community/instagram-comments/get-instagram-comments-1 api-reference/community-openapi.json GET /instagram_comments/{community_interaction_id} Get a single comment by given parameters # List messages in a conversation Source: https://developer.dashsocial.com/api-reference/community/instagram-messages/get-instagram-messages api-reference/community-openapi.json GET /conversations/instagram/{conversation_id}/messages Get a paginated list of messages sorted chronologicaly most recent first. # Delete tag Source: https://developer.dashsocial.com/api-reference/community/interaction-tags/delete-tag api-reference/community-openapi.json DELETE /tags/{tag_id} Deletes a tag by ID. # Get Tags Source: https://developer.dashsocial.com/api-reference/community/interaction-tags/get-tags api-reference/community-openapi.json GET /tags Get the tag details for a Dash Social brand # Create a tag Source: https://developer.dashsocial.com/api-reference/community/interaction-tags/post-tags api-reference/community-openapi.json POST /tags Creates a tag and assigns a random color to it # Get tiktok comments for a piece of media Source: https://developer.dashsocial.com/api-reference/community/tiktok-comments/get-tiktok-comments api-reference/community-openapi.json GET /tiktok_comments Get paginated result of all comments on media object with brand replies # Get a comment Source: https://developer.dashsocial.com/api-reference/community/tiktok-comments/get-tiktok-comments-1 api-reference/community-openapi.json GET /tiktok_comments/{community_interaction_id} Get a tiktok comment with replies # List messages in a Twitter conversation Source: https://developer.dashsocial.com/api-reference/community/twitter-messages/get-twitter-messages api-reference/community-openapi.json GET /conversations/twitter/{conversation_id}/messages Get a paginated list of messages sorted chronologically most recent first # Get a list of tweets Source: https://developer.dashsocial.com/api-reference/community/twitter-tweets/get-tweets api-reference/community-openapi.json GET /tweets Retrieve a list of top-level tweets with their respective flattened replies # Get a tweet Source: https://developer.dashsocial.com/api-reference/community/twitter-tweets/get-tweets-1 api-reference/community-openapi.json GET /tweets/{community_interaction_id} Get a single tweet by given parameters # Get a single YouTube comment Source: https://developer.dashsocial.com/api-reference/community/youtube-comments/get-youtube-comment api-reference/community-openapi.json GET /youtube_comments/{community_interaction_id} Get a YouTube comment with replies # Get a list of tweets Source: https://developer.dashsocial.com/api-reference/community/youtube-comments/get-youtube-comments api-reference/community-openapi.json GET /youtube_comments Get a paginated list of all root-level comments on media with brand replies # Patch a comment Source: https://developer.dashsocial.com/api-reference/community/youtube-comments/patch-youtube-comment api-reference/community-openapi.json PATCH /youtube_comments/{community_interaction_id} Currently to hide a YouTube comment # Create a new YouTube comment Source: https://developer.dashsocial.com/api-reference/community/youtube-comments/post-youtube-comments api-reference/community-openapi.json POST /youtube_comments Create a reply to a YouTube comment # Get report data Source: https://developer.dashsocial.com/api-reference/dashboard/get-report-data api-reference/dashboard-openapi.json GET /reports/data Retrieve report data for Owned, Earned, Community, Social Listening, TSI, and Social Advertising reports using query parameters. - See [Export dashboard report data via API](/guides/reporting/export-dashboard-report-data-via-api) for detailed guides on each report type. # Query report data with request body Source: https://developer.dashsocial.com/api-reference/dashboard/query-report-data api-reference/dashboard-openapi.json PUT /reports/data Retrieve report data for Competitive and Benchmark reports. Use this endpoint when you need to pass `competitor_source_account_ids` or `benchmarks` in the request body. - See [Export dashboard report data via API](/guides/reporting/export-dashboard-report-data-via-api) for detailed guides on each report type. # Introduction Source: https://developer.dashsocial.com/api-reference/introduction Authenticate and start querying the Dash Social API ## Before You Begin Make sure you have the following before making your first request: * Your Dash Social plan includes **API access** — contact Support if you're unsure * You are a **brand admin** — only admins can generate API keys ## Authentication The Dash Social API uses **Bearer token authentication**. Include your API key in the `Authorization` header on every request: ```bash theme={null} Authorization: Bearer {token} ``` Keep your token secret and never include it in client-side code. Always send API requests from your backend. ## Get Your API Key and Brand ID 1. In Dash Social, go to **Settings → API and Integrations → Developers**, or [click here](https://app.dashsocial.com/settings/developer_page) 2. Copy your **Brand ID** displayed next to your brand name 3. Click **Generate New API Key** and give it a name 4. Copy and securely save the key — it will only be shown once If you need an API key with access to multiple brands, contact Support. ## Verify Your Token After generating your key, call `/api/self` to confirm your token is valid and see which brands and permissions it has access to. ```bash theme={null} curl 'https://auth.dashsocial.com/api/self' \ -H 'Authorization: Bearer {token}' ``` The response includes: | Field | Description | | ------------------- | ------------------------------------------------------------------- | | `accessible_brands` | Array of brand IDs your key can access | | `brands` | Brand details including avatar, status, and org info | | `permissions` | Full permission matrix by feature (ads, campaigns, community, etc.) | | `plan` | Subscription and billing information | | `organization` | Company and org-level permission details | If you don't see an expected brand or permission, verify your token is still active in Settings. If issues persist, contact Support. ## Get Your Organization ID Several endpoints require an `organization_id`. The `/api/self` response you retrieved above includes it — look for `organization_id` at the top level: ```json theme={null} { "organization_id": 1, "organization": { "id": 1, "name": "Your Organization" } } ``` ## What's Next Query campaigns, galleries, media, products, and more Access community interactions, comments, and messages across channels # Add media to campaign Source: https://developer.dashsocial.com/api-reference/library/campaign/add-media-to-a-campaign api-reference/library-openapi.json POST /brands/{brand_id}/campaigns/{campaign_id}/media Adds owned media to a campaign. # Add UGC to campaign Source: https://developer.dashsocial.com/api-reference/library/campaign/add-ugc-media-to-a-campaign api-reference/library-openapi.json POST /brands/{brand_id}/campaigns/{campaign_id}/ugc Adds UGC media to a campaign. # Create a campaign Source: https://developer.dashsocial.com/api-reference/library/campaign/create-a-new-campaign api-reference/library-openapi.json POST /brands/{brand_id}/campaigns Creates a new campaign for a brand. # Delete a campaign Source: https://developer.dashsocial.com/api-reference/library/campaign/delete-campaign api-reference/library-openapi.json DELETE /brands/{brand_id}/campaigns/{campaign_id} Permanently deletes a campaign. # Search campaign ads Source: https://developer.dashsocial.com/api-reference/library/campaign/get-ads-for-a-campaign-and-source api-reference/library-openapi.json POST /brands/{brand_id}/campaigns/{campaign_id}/ads/search Searches for ads associated with a campaign by source channel. # Retrieve campaign relationships Source: https://developer.dashsocial.com/api-reference/library/campaign/get-brands-campaigns-relationships api-reference/library-openapi.json GET /brands/{brand_id}/campaigns/{campaign_id}/relationships Returns the relationship brands associated with a campaign. # Retrieve campaign UGC Source: https://developer.dashsocial.com/api-reference/library/campaign/get-brands-campaigns-ugc api-reference/library-openapi.json GET /brands/{brand_id}/campaigns/{campaign_id}/ugc Returns UGC media associated with a campaign. # Retrieve campaign media Source: https://developer.dashsocial.com/api-reference/library/campaign/get-campaigns-media api-reference/library-openapi.json GET /brands/{brand_id}/campaigns/{campaign_id}/media Returns owned media associated with a campaign. # Retrieve campaign statistics Source: https://developer.dashsocial.com/api-reference/library/campaign/get-campaigns-stats api-reference/library-openapi.json GET /brands/{brand_id}/campaigns/{campaign_id}/stats Returns aggregated performance statistics for a campaign. # Get campaigns stats overview Source: https://developer.dashsocial.com/api-reference/library/campaign/get-campaigns-stats-overview api-reference/library-openapi.json GET /brands/{brand_id}/campaigns/{campaign_id}/stats/overview # Get ad campaigns Source: https://developer.dashsocial.com/api-reference/library/campaign/get-the-ad-campaigns-of-a-dash-campaign api-reference/library-openapi.json GET /brands/{brand_id}/campaigns/{campaign_id}/ad_campaigns Returns the external ad campaigns (e.g. TikTok Ads, Meta Ads) linked to a Dash Social campaign. # Update a campaign Source: https://developer.dashsocial.com/api-reference/library/campaign/replace-campaign api-reference/library-openapi.json PUT /brands/{brand_id}/campaigns/{campaign_id} Updates all fields of a campaign. # Retrieve a campaign Source: https://developer.dashsocial.com/api-reference/library/campaign/retrieve-campaign api-reference/library-openapi.json GET /brands/{brand_id}/campaigns/{campaign_id} Returns details for a single campaign. # Retrieve campaigns Source: https://developer.dashsocial.com/api-reference/library/campaign/retrieve-campaigns api-reference/library-openapi.json GET /brands/{brand_id}/campaigns Returns a list of campaigns for a brand. # Update a campaign Source: https://developer.dashsocial.com/api-reference/library/campaign/update-campaign api-reference/library-openapi.json PATCH /brands/{brand_id}/campaigns/{campaign_id} Partially updates a campaign. Only the fields provided in the request body are updated. # Update campaign ad campaigns Source: https://developer.dashsocial.com/api-reference/library/campaign/update-the-ad-campaigns-of-a-dash-campaign api-reference/library-openapi.json PUT /brands/{brand_id}/campaigns/{campaign_id}/ad_campaigns Updates the ad campaigns linked to a Dash Social campaign. # Create a content tag Source: https://developer.dashsocial.com/api-reference/library/content-tags/create-content-tag api-reference/library-openapi.json POST /organizations/{organization_id}/content_tags Creates a new content tag for an organization. # Retrieve content tags Source: https://developer.dashsocial.com/api-reference/library/content-tags/list-content-tags api-reference/library-openapi.json GET /organizations/{organization_id}/content_tags Returns a list of content tags for an organization. # Add media to gallery Source: https://developer.dashsocial.com/api-reference/library/gallery/add-media-to-gallery api-reference/library-openapi.json POST /brands/{brand_id}/galleries/{gallery_id}/media Adds a list of media objects to a gallery. # Add media to Instagram LikeShop Source: https://developer.dashsocial.com/api-reference/library/gallery/add-media-to-likeshop-gallery api-reference/library-openapi.json POST /brands/{brand_id}/galleries/likeshop/media Adds media objects to the Instagram LikeShop gallery. # Create a gallery Source: https://developer.dashsocial.com/api-reference/library/gallery/create-gallery api-reference/library-openapi.json POST /brands/{brand_id}/galleries Creates a new gallery for a brand. # Delete a gallery Source: https://developer.dashsocial.com/api-reference/library/gallery/delete-gallery api-reference/library-openapi.json DELETE /brands/{brand_id}/galleries/{gallery_id} Permanently deletes a gallery. # Retrieve galleries statistics Source: https://developer.dashsocial.com/api-reference/library/gallery/get-galleries-stats-for-a-brand api-reference/library-openapi.json GET /brands/{brand_id}/galleries/stats Returns aggregated statistics across all galleries for a brand. # Retrieve Instagram LikeShop statistics Source: https://developer.dashsocial.com/api-reference/library/gallery/get-the-stats-for-a-brand-gallery api-reference/library-openapi.json GET /brands/{brand_id}/galleries/likeshop/stats Returns performance statistics for the Instagram LikeShop gallery. # Retrieve gallery statistics Source: https://developer.dashsocial.com/api-reference/library/gallery/get-the-stats-for-a-brand-gallery-1 api-reference/library-openapi.json GET /brands/{brand_id}/galleries/{gallery_id}/stats Returns performance statistics for a gallery. # Retrieve galleries Source: https://developer.dashsocial.com/api-reference/library/gallery/list-galleries api-reference/library-openapi.json GET /brands/{brand_id}/galleries Returns a list of galleries for a brand. # Retrieve Instagram LikeShop media Source: https://developer.dashsocial.com/api-reference/library/gallery/list-likeshop-gallery-media api-reference/library-openapi.json GET /brands/{brand_id}/galleries/likeshop/media Returns media items in the Instagram LikeShop gallery for a brand. # Retrieve TikTok LikeShop media Source: https://developer.dashsocial.com/api-reference/library/gallery/list-tiktok-likeshop-gallery-media api-reference/library-openapi.json GET /brands/{brand_id}/galleries/tiktok_likeshop/media Returns media items in the TikTok LikeShop gallery. # Retrieve a gallery Source: https://developer.dashsocial.com/api-reference/library/gallery/retrieve-gallery api-reference/library-openapi.json GET /brands/{brand_id}/galleries/{gallery_id} Returns details for a single gallery. # Retrieve TikTok LikeShop gallery Source: https://developer.dashsocial.com/api-reference/library/gallery/retrieve-gallery-for-tiktok-likeshop api-reference/library-openapi.json GET /brands/{brand_id}/galleries/tiktok_likeshop Returns details for the TikTok LikeShop gallery for a brand. # Update a gallery Source: https://developer.dashsocial.com/api-reference/library/gallery/update-gallery api-reference/library-openapi.json PATCH /brands/{brand_id}/galleries/{gallery_id} Updates a gallery's settings or metadata. # Create a media object Source: https://developer.dashsocial.com/api-reference/library/media/create-a-media-object api-reference/library-openapi.json POST /brands/{brand_id}/media/v2 Creates a new media object for a brand. # Retrieve a media object Source: https://developer.dashsocial.com/api-reference/library/media/get-media-object api-reference/library-openapi.json GET /brands/{brand_id}/media/v2/{media_id} Returns details for a single media object by ID. # Retrieve media Source: https://developer.dashsocial.com/api-reference/library/media/retrieve-media api-reference/library-openapi.json PUT /brands/{brand_id}/media/v2 Returns a paginated list of media objects for a brand. Filter by platform, date range, media type, and more using the request body. Need help getting started? Check out the [Get post performance data across all channels](/guides/reporting/get-post-performance-data-across-all-channels) guide for use cases, filters, and sample responses. # Retrieve product media Source: https://developer.dashsocial.com/api-reference/library/product/retrieve-product-media api-reference/library-openapi.json GET /public/brands/{brand_id}/products/media Returns media associated with products for a brand. No authentication required. # Archive products Source: https://developer.dashsocial.com/api-reference/library/product/update-the-archived-status-of-a-list-of-products api-reference/library-openapi.json PATCH /brands/{brand_id}/products/archive Updates the archived status of a list of products. # Retrieve gallery media Source: https://developer.dashsocial.com/api-reference/library/publicgallery/get-publicbrands-galleries-media api-reference/library-openapi.json GET /public/brands/{brand_id}/galleries/{gallery_id}/media Returns media items from a gallery. This is a public endpoint — no authorization required. # Create a Bluesky post Source: https://developer.dashsocial.com/api-reference/scheduler/bluesky/create-bluesky-scheduled-posts api-reference/scheduler-openapi.json POST /bluesky/scheduled_posts Create a new Bluesky post. This endpoint has platform-specific fields and publishing rules. See the [full scheduling guide](/guides/scheduler/schedule-social-media-posts-with-the-dash-api) for a complete walkthrough including media upload, publishing modes, and examples. ## Bluesky-specific fields | Parameter | Description | | --------- | ----------------- | | `text` | Post caption text | ## Publishing modes | Mode | `status` | `auto_publish` | `timestamp` | | ------------------- | ---------------- | ----------------- | ------------ | | Publish immediately | `AUTOPUBLISHING` | `true` | Not required | | Schedule for later | `SCHEDULED` | `true` | Required | | Save as draft | `DRAFT` | `true` or `false` | Optional | ## Example request ```json theme={null} { "auto_publish": true, "brand_id": 144, "status": "SCHEDULED", "media_ids": [650431494, 650482495, 650419615, 650418969], "timestamp": "2026-03-12T22:30:00.000Z", "text": "A few recent favorites from our spring inspiration board." } ``` ## Notes * `auto_publish` is always treated as `true`, even if `false` is provided. * Caption-only posts (no media) are supported. * Image posts support up to **4 images**. * Bluesky supports **image media only**. Video and mixed media are not supported. # Delete a Bluesky post Source: https://developer.dashsocial.com/api-reference/scheduler/bluesky/delete-bluesky-scheduled-post api-reference/scheduler-openapi.json DELETE /bluesky/scheduled_posts/{post_id} Delete a specific Bluesky post by post ID. # Get a Bluesky post Source: https://developer.dashsocial.com/api-reference/scheduler/bluesky/get-bluesky-scheduled-post api-reference/scheduler-openapi.json GET /bluesky/scheduled_posts/{post_id} Get a specific Bluesky post by post ID. # Get Bluesky posts Source: https://developer.dashsocial.com/api-reference/scheduler/bluesky/list-bluesky-scheduled-posts api-reference/scheduler-openapi.json GET /bluesky/scheduled_posts Get a list of Bluesky posts for the brand. # Update a Bluesky post Source: https://developer.dashsocial.com/api-reference/scheduler/bluesky/update-bluesky-scheduled-post api-reference/scheduler-openapi.json PATCH /bluesky/scheduled_posts/{post_id} # Create a Facebook post Source: https://developer.dashsocial.com/api-reference/scheduler/facebook/create-facebook-scheduled-posts api-reference/scheduler-openapi.json POST /facebook/scheduled_posts Create a new Facebook post. This endpoint has platform-specific fields and publishing rules. See the [full scheduling guide](/guides/scheduler/schedule-social-media-posts-with-the-dash-api) for a complete walkthrough including media upload, publishing modes, and examples. ## Facebook-specific fields | Parameter | Description | | --------------- | ----------------------------------------------------------------- | | `post_type` | **Required.** `POST` or `REEL` | | `message` | Post caption text | | `first_comment` | Optional first comment (not supported when `auto_publish: false`) | | `link` | Optional URL to create a link-based post with preview | ## Publishing modes | Mode | `status` | `auto_publish` | `timestamp` | | ------------------- | ---------------- | ----------------- | ------------ | | Publish immediately | `AUTOPUBLISHING` | `true` | Not required | | Schedule for later | `SCHEDULED` | `true` | Required | | Save as draft | `DRAFT` | `true` or `false` | Optional | ## Example request ```json theme={null} { "auto_publish": true, "brand_id": 144, "status": "SCHEDULED", "message": "Check out our newest launch!", "media_ids": [621242772], "timestamp": "2026-03-10T15:00:00Z", "first_comment": "Drop your thoughts below!", "post_type": "POST" } ``` ## Notes * Standard `POST` can be created without media (caption-only supported). * `REEL` posts require **video media**. * `first_comment` is not supported when `auto_publish` is `false`. * `POST` supports up to **10 images** or **1 video**. Images and videos cannot be mixed. # Delete a Facebook post Source: https://developer.dashsocial.com/api-reference/scheduler/facebook/delete-facebook-scheduled-post api-reference/scheduler-openapi.json DELETE /facebook/scheduled_posts/{post_id} Delete a specific Facebook post by post ID. # Get a Facebook post Source: https://developer.dashsocial.com/api-reference/scheduler/facebook/get-facebook-scheduled-post api-reference/scheduler-openapi.json GET /facebook/scheduled_posts/{post_id} Get a specific Facebook post by post ID. # Get Facebook posts Source: https://developer.dashsocial.com/api-reference/scheduler/facebook/list-facebook-scheduled-posts api-reference/scheduler-openapi.json GET /facebook/scheduled_posts Get a list of Facebook posts for the brand. # Update a Facebook post Source: https://developer.dashsocial.com/api-reference/scheduler/facebook/update-facebook-scheduled-post api-reference/scheduler-openapi.json PATCH /facebook/scheduled_posts/{post_id} Update a specific Facebook post by post ID. # Create an Instagram post Source: https://developer.dashsocial.com/api-reference/scheduler/instagram/create-instagram-scheduled-posts api-reference/scheduler-openapi.json POST /instagram/scheduled_posts Create a new Instagram post. This endpoint has platform-specific fields and publishing rules. See the [full scheduling guide](/guides/scheduler/schedule-social-media-posts-with-the-dash-api) for a complete walkthrough including media upload, publishing modes, and examples. ## Instagram-specific fields | Parameter | Description | | --------------- | ----------------------------------------------------------------- | | `post_type` | **Required.** `FEED`, `STORY`, or `REEL` | | `caption` | Post caption text | | `first_comment` | Optional first comment (not supported when `auto_publish: false`) | ## Publishing modes | Mode | `status` | `auto_publish` | `timestamp` | | ------------------- | ---------------- | ----------------- | ------------ | | Publish immediately | `AUTOPUBLISHING` | `true` | Not required | | Schedule for later | `SCHEDULED` | `true` | Required | | Save as draft | `DRAFT` | `true` or `false` | Optional | ## Example request ```json theme={null} { "auto_publish": true, "brand_id": 144, "status": "SCHEDULED", "caption": "Launching our new product today!", "first_comment": "Let us know what you think 👇", "media_ids": [621242772], "post_type": "FEED", "timestamp": "2026-03-10T15:00:00Z" } ``` ## Notes * `post_type` determines whether the post is a `FEED`, `STORY`, or `REEL`. * `first_comment` is not supported when `auto_publish` is `false`. * Auto-publish posts must include `media_ids`. * `POST`, `REEL`, and `STORY` drafts can be created without media. * Instagram Post supports up to **10 media items** (images and videos mixed). Reels support **1 video**. Stories support **1 item** for auto-publish. # Delete an Instagram post Source: https://developer.dashsocial.com/api-reference/scheduler/instagram/delete-instagram-scheduled-post api-reference/scheduler-openapi.json DELETE /instagram/scheduled_posts/{post_id} Delete a specific Instagram post by post ID. # Get an Instagram post Source: https://developer.dashsocial.com/api-reference/scheduler/instagram/get-instagram-scheduled-post api-reference/scheduler-openapi.json GET /instagram/scheduled_posts/{post_id} Get a specific Instagram post by post ID. # Get Instagram posts Source: https://developer.dashsocial.com/api-reference/scheduler/instagram/list-instagram-scheduled-posts api-reference/scheduler-openapi.json GET /instagram/scheduled_posts Get a list of Instagram posts for the brand. # Update an Instagram post Source: https://developer.dashsocial.com/api-reference/scheduler/instagram/update-instagram-scheduled-post api-reference/scheduler-openapi.json PATCH /instagram/scheduled_posts/{post_id} Update a specific Instagram post by post ID. # Create a LinkedIn post Create a new LinkedIn post. Source: https://developer.dashsocial.com/api-reference/scheduler/linkedin/create-linkedin-scheduled-posts api-reference/scheduler-openapi.json POST /linkedin/scheduled_posts This endpoint has platform-specific fields and publishing rules. See the [full scheduling guide](/guides/scheduler/schedule-social-media-posts-with-the-dash-api) for a complete walkthrough including media upload, publishing modes, and examples. ## LinkedIn-specific fields | Parameter | Description | | --------- | ----------------- | | `text` | Post caption text | ## Publishing modes | Mode | `status` | `auto_publish` | `timestamp` | | ------------------- | ---------------- | ----------------- | ------------ | | Publish immediately | `AUTOPUBLISHING` | `true` | Not required | | Schedule for later | `SCHEDULED` | `true` | Required | | Save as draft | `DRAFT` | `true` or `false` | Optional | ## Example request ```json theme={null} { "auto_publish": true, "brand_id": 144, "status": "SCHEDULED", "text": "We're excited to share our newest launch.", "media_ids": [621242772], "timestamp": "2026-03-10T15:00:00Z" } ``` ## Notes * `auto_publish: false` is **not supported**. Always set `auto_publish: true`. * Caption-only posts (no media) are supported. * Image posts support up to **20 images**. Video posts support **1 video only**. Images and videos cannot be mixed. # Delete a LinkedIn post Source: https://developer.dashsocial.com/api-reference/scheduler/linkedin/delete-linkedin-scheduled-post api-reference/scheduler-openapi.json DELETE /linkedin/scheduled_posts/{post_id} Delete a specific LinkedIn post by post ID. # Get an LinkedIn post Source: https://developer.dashsocial.com/api-reference/scheduler/linkedin/get-linkedin-scheduled-post api-reference/scheduler-openapi.json GET /linkedin/scheduled_posts/{post_id} Get a specific LinkedIn post by post ID. # Get LinkedIn posts Source: https://developer.dashsocial.com/api-reference/scheduler/linkedin/list-linkedin-scheduled-posts api-reference/scheduler-openapi.json GET /linkedin/scheduled_posts Get a list of LinkedIn posts for the brand. # Update a LinkedIn post Source: https://developer.dashsocial.com/api-reference/scheduler/linkedin/update-linkedin-scheduled-post api-reference/scheduler-openapi.json PATCH /linkedin/scheduled_posts/{post_id} Update a specific LinkedIn post by post ID. # Create a Snapchat post Source: https://developer.dashsocial.com/api-reference/scheduler/snapchat/create-snapchat-scheduled-posts api-reference/scheduler-openapi.json POST /snapchat/scheduled_posts Create a new Snapchat post (Story or Spotlight). This endpoint has platform-specific fields and publishing rules. See the [full scheduling guide](/guides/scheduler/schedule-social-media-posts-with-the-dash-api) for a complete walkthrough including media upload, publishing modes, and examples. ## Snapchat-specific fields | Parameter | Description | | ----------------- | ------------------------------------------------------------------------------------- | | `post_type` | **Required.** `STORY` or `SPOTLIGHT`. | | `description` | Optional caption text for `SPOTLIGHT` posts. **Not supported** for `STORY` posts. | | `save_to_profile` | **Required for `SPOTLIGHT`.** Boolean. Saves the post to the public Snapchat profile. | | `locale` | **Required for `SPOTLIGHT`.** Locale for the post, for example `en_US`. | ## Publishing modes | Mode | `status` | `auto_publish` | `timestamp` | | ------------------- | ---------------- | -------------- | ------------ | | Publish immediately | `AUTOPUBLISHING` | `true` | Not required | | Schedule for later | `SCHEDULED` | `true` | Required | ## Example requests **Story** ```json theme={null} { "auto_publish": true, "brand_id": 144, "status": "SCHEDULED", "media_ids": [650029769], "timestamp": "2026-03-12T16:05:00.000Z", "post_type": "STORY" } ``` **Spotlight** ```json theme={null} { "brand_id": 144, "status": "SCHEDULED", "media_ids": [648771867], "timestamp": "2026-03-12T18:00:00.000Z", "description": "3 quick ways to style oversized sweaters this fall 🍂", "post_type": "SPOTLIGHT", "save_to_profile": true, "locale": "en_US" } ``` ## Notes * `auto_publish: false` is **not supported**. Always set `auto_publish: true`. * `media_ids` is required for all Snapchat posts. * `STORY` posts support image or video. `description` is not available for Story posts. * `SPOTLIGHT` posts require video media. `save_to_profile` and `locale` are required. # Delete a Snapchat post Source: https://developer.dashsocial.com/api-reference/scheduler/snapchat/delete-snapchat-scheduled-post api-reference/scheduler-openapi.json DELETE /snapchat/scheduled_posts/{post_id} # Get a Snapchat post Source: https://developer.dashsocial.com/api-reference/scheduler/snapchat/get-snapchat-scheduled-post api-reference/scheduler-openapi.json GET /snapchat/scheduled_posts/{post_id} Get a specific Snapchat post by post ID. # Get Snapchat posts Source: https://developer.dashsocial.com/api-reference/scheduler/snapchat/list-snapchat-scheduled-posts api-reference/scheduler-openapi.json GET /snapchat/scheduled_posts Get a list of Snapchat posts for the brand. # Update a Snapchat post Source: https://developer.dashsocial.com/api-reference/scheduler/snapchat/update-snapchat-scheduled-post api-reference/scheduler-openapi.json PATCH /snapchat/scheduled_posts/{post_id} # Create a Threads post Source: https://developer.dashsocial.com/api-reference/scheduler/threads/create-threads-scheduled-posts api-reference/scheduler-openapi.json POST /threads/scheduled_posts Create a new Threads post. This endpoint has platform-specific fields and publishing rules. See the [full scheduling guide](/guides/scheduler/schedule-social-media-posts-with-the-dash-api) for a complete walkthrough including media upload, publishing modes, and examples. ## Threads-specific fields | Parameter | Description | | --------- | ----------------- | | `text` | Post caption text | ## Publishing modes | Mode | `status` | `auto_publish` | `timestamp` | | ------------------- | ---------------- | ----------------- | ------------ | | Publish immediately | `AUTOPUBLISHING` | `true` | Not required | | Schedule for later | `SCHEDULED` | `true` | Required | | Save as draft | `DRAFT` | `true` or `false` | Optional | ## Example request ```json theme={null} { "auto_publish": true, "brand_id": 144, "status": "SCHEDULED", "text": "Something exciting is coming.", "media_ids": [621242772], "timestamp": "2026-03-10T15:00:00Z" } ``` ## Notes * `auto_publish` is always treated as `true`, even if `false` is provided. * Caption-only posts (no media) are supported. * Supports up to **20 images**. Video is not currently supported. # Delete a Threads post Source: https://developer.dashsocial.com/api-reference/scheduler/threads/delete-threads-scheduled-post api-reference/scheduler-openapi.json DELETE /threads/scheduled_posts/{post_id} Delete a specific Threads post by post ID. # Get a Threads post Source: https://developer.dashsocial.com/api-reference/scheduler/threads/get-threads-scheduled-post api-reference/scheduler-openapi.json GET /threads/scheduled_posts/{post_id} Get a specific Threads post by post ID. # Get Threads posts Get a list of Threads posts for the brand(s). Source: https://developer.dashsocial.com/api-reference/scheduler/threads/list-threads-scheduled-posts api-reference/scheduler-openapi.json GET /threads/scheduled_posts # Update a Threads post Source: https://developer.dashsocial.com/api-reference/scheduler/threads/update-threads-scheduled-post api-reference/scheduler-openapi.json PATCH /threads/scheduled_posts/{post_id} # Create a TikTok post Source: https://developer.dashsocial.com/api-reference/scheduler/tiktok/create-tiktok-scheduled-posts api-reference/scheduler-openapi.json POST /tiktok/scheduled_posts Create a new TikTok post. This endpoint has platform-specific fields and publishing rules. See the [full scheduling guide](/guides/scheduler/schedule-social-media-posts-with-the-dash-api) for a complete walkthrough including media upload, publishing modes, and examples. ## TikTok-specific fields | Parameter | Description | | ----------------- | ---------------------------------------------------------------------------- | | `text` | Caption for the TikTok post | | `disable_comment` | Optional. Set to `true` to disable comments on the post. | | `disable_duet` | Optional. Set to `true` to prevent users from creating duets with the video. | | `disable_stitch` | Optional. Set to `true` to prevent users from stitching the video. | ## Publishing modes | Mode | `status` | `auto_publish` | `timestamp` | | ------------------- | ---------------- | ----------------- | ------------ | | Publish immediately | `AUTOPUBLISHING` | `true` | Not required | | Schedule for later | `SCHEDULED` | `true` | Required | | Save as draft | `DRAFT` | `true` or `false` | Optional | ## Example request ```json theme={null} { "auto_publish": true, "brand_id": 144, "status": "SCHEDULED", "text": "Behind the scenes of our launch", "media_ids": [621242772], "timestamp": "2026-03-10T15:00:00Z", "disable_comment": false, "disable_duet": false, "disable_stitch": false } ``` ## Notes * TikTok **only supports video media**. Image uploads are not supported. * Auto-publish posts require video media. Drafts can be created without media. * Only **1 video** can be attached to a TikTok post. # Delete a TikTok post Source: https://developer.dashsocial.com/api-reference/scheduler/tiktok/delete-tiktok-scheduled-post api-reference/scheduler-openapi.json DELETE /tiktok/scheduled_posts/{post_id} Delete a specific TikTok post by post ID. # Get a TikTok post Source: https://developer.dashsocial.com/api-reference/scheduler/tiktok/get-tiktok-scheduled-post api-reference/scheduler-openapi.json GET /tiktok/scheduled_posts/{post_id} Get a specific TikTok post by post ID. # Get TikTok posts Source: https://developer.dashsocial.com/api-reference/scheduler/tiktok/list-tiktok-scheduled-posts api-reference/scheduler-openapi.json GET /tiktok/scheduled_posts Get a list of TikTok posts for the brand. # Update a TikTok post Source: https://developer.dashsocial.com/api-reference/scheduler/tiktok/update-tiktok-scheduled-post api-reference/scheduler-openapi.json PATCH /tiktok/scheduled_posts/{post_id} Update a specific TikTok post by post ID. # Create a Twitter post Source: https://developer.dashsocial.com/api-reference/scheduler/twitter/create-twitter-scheduled-posts api-reference/scheduler-openapi.json POST /twitter/scheduled_posts Create a new Twitter post. This endpoint has platform-specific fields and publishing rules. See the [full scheduling guide](/guides/scheduler/schedule-social-media-posts-with-the-dash-api) for a complete walkthrough including media upload, publishing modes, and examples. ## X-specific fields | Parameter | Description | | -------------- | ----------- | | `tweet_status` | Post text | ## Publishing modes | Mode | `status` | `auto_publish` | `timestamp` | | ------------------- | ---------------- | ----------------- | ------------ | | Publish immediately | `AUTOPUBLISHING` | `true` | Not required | | Schedule for later | `SCHEDULED` | `true` | Required | | Save as draft | `DRAFT` | `true` or `false` | Optional | ## Example request ```json theme={null} { "auto_publish": true, "brand_id": 144, "status": "SCHEDULED", "timestamp": "2026-03-10T15:00:00Z", "tweet_status": "Launching something new today 🚀" } ``` ## Notes * Standard X posts support up to **280 characters**. * Accounts with **X Premium** can publish posts up to **25,000 characters**. * Caption-only posts (no media) are supported. * Supports up to **4 images** or **1 video**. Images and videos cannot be mixed. # Delete a Twitter post Source: https://developer.dashsocial.com/api-reference/scheduler/twitter/delete-twitter-scheduled-post api-reference/scheduler-openapi.json DELETE /twitter/scheduled_posts/{post_id} Delete a specific Twitter post by post ID. # Get a Twitter post Source: https://developer.dashsocial.com/api-reference/scheduler/twitter/get-twitter-scheduled-post api-reference/scheduler-openapi.json GET /twitter/scheduled_posts/{post_id} Get a specific Twitter post by post ID. # Get Twitter posts Source: https://developer.dashsocial.com/api-reference/scheduler/twitter/list-twitter-scheduled-posts api-reference/scheduler-openapi.json GET /twitter/scheduled_posts Get a list of Twitter posts for the brand. # Update a Twitter post Source: https://developer.dashsocial.com/api-reference/scheduler/twitter/update-twitter-scheduled-post api-reference/scheduler-openapi.json PATCH /twitter/scheduled_posts/{post_id} Update a specific Twitter post by post ID. # Create a YouTube post Source: https://developer.dashsocial.com/api-reference/scheduler/youtube/create-youtube-scheduled-posts api-reference/scheduler-openapi.json POST /youtube/scheduled_posts Create a new YouTube post. This endpoint has platform-specific fields and publishing rules. See the [full scheduling guide](/guides/scheduler/schedule-social-media-posts-with-the-dash-api) for a complete walkthrough including media upload, publishing modes, and examples. ## YouTube-specific fields | Parameter | Description | | ------------------------ | --------------------------------------------------------- | | `title` | **Required.** Title of the YouTube video. | | `description` | Optional description for the video. | | `declared_made_for_kids` | **Required.** `"true"` or `"false"` for COPPA compliance. | ## Publishing modes | Mode | `status` | `auto_publish` | `timestamp` | | ------------------- | ---------------- | -------------- | ------------ | | Publish immediately | `AUTOPUBLISHING` | `true` | Not required | | Schedule for later | `SCHEDULED` | `true` | Required | ## Example request ```json theme={null} { "auto_publish": true, "brand_id": 144, "status": "SCHEDULED", "title": "Product Launch", "description": "Watch our newest launch announcement.", "media_ids": [621242772], "timestamp": "2026-03-10T15:00:00Z", "declared_made_for_kids": "false" } ``` ## Notes * `auto_publish: false` is **not supported**. Always set `auto_publish: true`. * YouTube **only supports video media**. Drafts without media are not supported. * Only **1 video** can be attached per post. * `declared_made_for_kids` is required to comply with COPPA. # Delete a YouTube post Source: https://developer.dashsocial.com/api-reference/scheduler/youtube/delete-youtube-scheduled-post api-reference/scheduler-openapi.json DELETE /youtube/scheduled_posts/{post_id} # Get a YouTube post Source: https://developer.dashsocial.com/api-reference/scheduler/youtube/get-youtube-scheduled-post api-reference/scheduler-openapi.json GET /youtube/scheduled_posts/{post_id} Get a specific YouTube post by post ID. # Get YouTube posts Source: https://developer.dashsocial.com/api-reference/scheduler/youtube/list-youtube-scheduled-posts api-reference/scheduler-openapi.json GET /youtube/scheduled_posts Get a list of YouTube posts for the brand. # Update a YouTube post Source: https://developer.dashsocial.com/api-reference/scheduler/youtube/update-youtube-scheduled-post api-reference/scheduler-openapi.json PATCH /youtube/scheduled_posts/{post_id} # Ads Account Requirement for Certain Facebook, TikTok, and Instagram Metrics Source: https://developer.dashsocial.com/changelog/ads-account-requirement-for-certain-facebook-tiktok-and-instagram-metrics Certain metrics now require connected Ads accounts for Facebook, TikTok, and Instagram. Dash Social APIs has implemented new requirements for accessing paid social data. Certain metrics now require connected Ads accounts across Facebook, TikTok, and Instagram. * **Impacted Endpoint:** `GET https://dashboard.dashsocial.com/reports/data` * **New Error:** `no_ad_account_matching_report_channels` — returned when a request includes metrics that require Ads data but the brand does not have the required Ads account connected. ## Platform-specific requirements **Facebook** — Metrics designated as "Organic only" or "Promoted only" require a Meta Ads connection. Combined "Total (Organic + Promoted)" and account-level metrics work without an Ads account. **TikTok** — "Organic only" or "Promoted only" metrics require a TikTok Ads account. "Organic + Promoted" and account-level metrics function without an Ads connection. **Instagram** — Any metrics representing "Total (Organic + Promoted)" performance require a connected Meta Ads account. ## Recommended actions * Ensure appropriate Ads accounts are connected when requesting Ads-dependent metrics. * Prioritize combined metrics where available. * Consider separating Ads-dependent and non-Ads-dependent metric queries into different API calls. # Community API: Migrate DMs to Message-Level Interactions Source: https://developer.dashsocial.com/changelog/community-api-migrate-dms-to-message-level-interactions Direct Messages (DMs) in the Community API are moving from **conversation-level** to **message-level** interactions. This affects how you retrieve messages, read message content, and reply to users across all platforms. > Comment-based interactions (Facebook, Instagram, TikTok, YouTube) are **not affected**. **Endpoints:** `GET /community_interactions`, `GET /conversations/{conversation_id}`, `POST|PATCH /conversations/{conversation_id}/messages`, `PATCH /messages/{id}` **Action Required:** Update endpoints, field references, and filters **Impact Level:** Breaking Change *** # Required Action ## Update Field References `GET /community_interactions` now returns one result per **message** instead of per **conversation**. For example, if a user sends 3 messages, they will appear as 3 separate results instead of 1 thread. Read message content directly from `text`. ## Update Conversation ID References Existing conversation IDs will be migrated as part of this change. Old conversation IDs will not work with the new endpoints after the effective date. ## Update Endpoints The new endpoints apply to all platforms. Platform-specific endpoints are deprecated. | Deprecated | Replace With | | ------------------------------------------------------------------------ | -------------------------------------- | | `GET /conversations/{platform}/{conversation_id}/messages` | `GET /conversations/{conversation_id}` | | `PATCH /conversations/instagram/{conversation_id}/messages/{message_id}` | `PATCH /messages/{id}` | ## Updated Response Structure `PATCH /community_interactions/{message_id}` now includes a `conversation` object in its response and writes actions at the message level. ## Update Filters | Deprecated Field | Replace With | | ---------------- | ------------ | | `is_archived` | `is_closed` | `is_archived` will continue to work during migration. *** ## Workflow Comparison ### Before (Conversation-Level) 1. `GET /community_interactions` * Returns conversation summaries 2. `GET /conversations/{platform}/{conversation_id}/messages` * Fetch full message thread 3. `POST /conversations/{platform}/{conversation_id}/messages` * Send reply 4. `PATCH /conversations/{platform}/{conversation_id}/messages/{message_id}` * Update message ### After (Message-Level) 1. `GET /community_interactions` * Returns individual messages * Use `text` for content * Includes `conversation_id` 2. *(Optional)* `GET /conversations/{conversation_id}` * Fetch full thread if needed 3. `POST /conversations/{conversation_id}/messages` * Send reply 4. `PATCH /community_interactions/{message_id}` * Update message *** # Additional Changes **Reporting APIs:** The following endpoints now include DM messages in their calculations. If your brand has active DMs, expect higher counts in volume and sentiment metrics. * `POST /sentiment_distribution_stats` * `POST /sentiment_time_series` * `POST /volume_time_series` * `POST /top_keywords` * `GET /overview_stats` *** If you are unsure whether your integration is impacted, please contact our team for assistance. # Deprecation: SINGLE_METRIC Report Type Source: https://developer.dashsocial.com/changelog/deprecation-single-metric-report-type The SINGLE_METRIC value for report_type is being deprecated. Replace with TOTAL_METRIC before June 30, 2026. **Breaking Change — Effective June 30, 2026.** Requests using `report_type=SINGLE_METRIC` will return a `400` error after this date. The `SINGLE_METRIC` value for the `report_type` parameter is being deprecated and will be removed from the Dashboard Reports API. * **Endpoint:** `GET https://dashboard.dashsocial.com/reports/data` * **Action Required:** Replace with `TOTAL_METRIC` ## Required action Update your API calls to use: ``` report_type=TOTAL_METRIC ``` If your query does not include the `report_type` parameter, add `report_type=TOTAL_METRIC` to your request. There are no changes to the response structure or returned data. This is a direct parameter replacement. ## Example **Before:** ``` GET https://dashboard.dashsocial.com/reports/data?...&report_type=SINGLE_METRIC ``` **After:** ``` GET https://dashboard.dashsocial.com/reports/data?...&report_type=TOTAL_METRIC ``` # Multi-Brand Support Added to the Community API (brand_ids) Source: https://developer.dashsocial.com/changelog/multi-brand-support-added-to-the-community-api-brand_ids The Community API now supports requesting multiple brands per request via the new brand_ids parameter; single-brand brand_id support ends May 1, 2025. ## What's Changing? Previously, the Community API only supported a single `brand_id` per request. You can now request data for multiple brands at once using the new `brand_ids` parameter with a comma-separated list. > **Note:** Even if your account is associated with only one brand, we kindly ask that you update your API calls to use `brand_ids` to ensure continued compatibility. ## What You Need to Update Please adjust the query parameters based on your use case. ### 1. `/community_interactions` **Before (Single Brand):** ```http theme={null} GET https://community.dashhudson.com/community_interactions?brand_id=1 ``` **After (Multi-Brand Support):** ```http theme={null} GET https://community.dashhudson.com/community_interactions?brand_ids=1,2,3 ``` ### 2. `/community_interactions/unread_interaction_counts` **Before (Single Brand — Path Parameter):** ```http theme={null} GET https://community.dashhudson.com/brands/{brand_id}/community_interactions/unread_counts ``` **After (Multi-Brand Support — Query Parameter):** ```http theme={null} POST https://community.dashhudson.com/community_interactions/unread_interaction_counts ``` Body: ```json theme={null} { "source_updated_after": "2025-01-15T00:00:00-07:00", "source_updated_before": "2025-02-11T23:59:59-07:00", "types": "FACEBOOK_COMMENT,FACEBOOK_CONVERSATION,FACEBOOK_ADS_COMMENT,INSTAGRAM_COMMENT,INSTAGRAM_CONVERSATION,INSTAGRAM_ADS_COMMENT,TIKTOK_COMMENT,TIKTOK_COMMENT_MENTION,TWITTER_CONVERSATION,TWITTER_MENTION,TWITTER_QUOTE,TWITTER_RETWEET,YOUTUBE_COMMENT", "brand_ids": [1, 2, 3] } ``` ### 3. `/tags` **Before (Single Brand):** ```http theme={null} GET https://community.dashhudson.com/tags?brand_id=1 ``` **After (Multi-Brand Support):** ```http theme={null} GET https://community.dashhudson.com/tags?brand_ids=1,2,3 ``` ### 4. `/overview_stats` **Before (Single Brand):** ```http theme={null} GET https://community.dashhudson.com/brands/{brand_id}/overview_stats ``` **After (Multi-Brand Support):** ```http theme={null} GET https://community.dashhudson.com/overview_stats?brand_ids=1,2,3 ``` ### 5. `/sentiment_distribution_stats` **Before (Single Brand):** ```http theme={null} PUT https://community.dashhudson.com/brands/{brand_id}/sentiment_distribution_stats ``` **After (Multi-Brand Support):** ```http theme={null} POST https://community.dashhudson.com/sentiment_distribution_stats ``` ```json theme={null} { "brand_ids": [1, 2, 3, 4] } ``` ### 6. `/sentiment_time_series` **Before (Single Brand):** ```http theme={null} GET https://community.dashhudson.com/brands/{brand_id}/sentiment_time_series ``` **After (Multi-Brand Support):** ```http theme={null} POST https://community.dashhudson.com/sentiment_time_series ``` ```json theme={null} { "brand_ids": [1, 2, 3, 4] } ``` ### 7. `/top_keywords` **Before (Single Brand):** ```http theme={null} PUT https://community.dashhudson.com/brands/{brand_id}/top_keywords ``` **After (Multi-Brand Support):** ```http theme={null} POST https://community.dashhudson.com/top_keywords ``` ```json theme={null} { "brand_ids": [1, 2, 3, 4] } ``` ### 8. `/volume_time_series` **Before (Single Brand):** ```http theme={null} GET https://community.dashhudson.com/brands/{brand_id}/volume_time_series ``` **After (Multi-Brand Support):** ```http theme={null} POST https://community.dashhudson.com/volume_time_series ``` ```json theme={null} { "brand_ids": [1, 2, 3, 4] } ``` ## Next Steps * Review and update any existing API calls that use `brand_id` to use the new `brand_ids` format. * Test your requests to confirm they return expected results for multiple brands. * No other parameters or functionality are affected — just a more flexible way to query! ## Deprecation Timeline Please note that support for the previous single-brand API format will end on **May 1, 2025**. We recommend updating your API calls promptly to avoid any disruptions. If you have any questions or need help making the update, feel free to reach out — we're happy to assist. # Facebook Metrics API Change Source: https://developer.dashsocial.com/changelog/nov-15-2025-facebook-metrics-api-change Facebook is deprecating and updating several metrics starting November 15, 2025. Facebook is deprecating and updating several metrics starting November 15, 2025. These changes may impact your API queries and data outputs. Review and update your integration to avoid errors or data gaps. [Learn More](https://help.dashsocial.com/hc/en-us/articles/40898506628749-Facebook-Metric-Updates-November-2025) ## Impacted endpoints The following endpoints may return errors or changed values if deprecated metrics are queried: * `https://dashboard.dashsocial.com/reports/data` * `https://library-backend.dashsocial.com/brands/{brand_id}/media/v2` * `https://library-backend.dashsocial.com/brands/{brand_id}/campaigns/{campaign_id}/media` * `https://library-backend.dashsocial.com/brands/{brand_id}/galleries/{gallery_id}/media` ## What's changing The following metrics in Dash Social are being discontinued: * **Page Likes** will be labeled as "Discontinued". * **Impressions** will be labeled as "Discontinued" and replaced with the new **Views** metric at both the page and post level. * **Total Plays** will be labeled as "Discontinued" and replaced with the new **Views** metric. * **Reels Effectiveness** will be replaced with **Effectiveness**. * **Link Clicks - Organic** will be labeled as "Discontinued". A new **Link Clicks - Total** metric will be available, which includes a breakdown of organic and promoted totals with a connected Meta Ads account. | Metric Name | Old Metric ID | Replaced By | Reports Affected | | --------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | | Page Likes | `TOTAL_PAGE_LIKES` | — | Graph Report, Metric Report | | Total Plays | `REELS_FB_REELS_TOTAL_PLAYS` | By Account Activity: Views - Organic: `PAGE_VIEWS_ORGANIC`, Views - Promoted: `PAGE_VIEWS_PAID`, Views - Organic + Promoted: `PAGE_VIEWS_PAID_AND_ORGANIC`. By Post: Views - Organic: `ORGANIC_VIEWS_BY_POST`, Views - Promoted: `PAID_VIEWS_BY_POST`, Views - Organic + Promoted: `PAID_AND_ORGANIC_VIEWS_BY_POST` | Graph Report, Metric Report | | Impressions | `IMPRESSIONS` | By Account Activity: Views - Organic: `PAGE_VIEWS_ORGANIC`, Views - Promoted: `PAGE_VIEWS_PAID`, Views - Organic + Promoted: `PAGE_VIEWS_PAID_AND_ORGANIC`. By Post: Views - Organic: `ORGANIC_VIEWS_BY_POST`, Views - Promoted: `PAID_VIEWS_BY_POST`, Views - Organic + Promoted: `PAID_AND_ORGANIC_VIEWS_BY_POST` | Graph Report, Metric Report | | Reels Effectiveness | `reel.effectiveness` | Effectiveness — `effectiveness` | Post | | Link Clicks - Organic | `organic_link_clicks` | Link Clicks - Total — `link_clicks` | Post | ## What you need to do * Replace deprecated metric IDs in API queries. * Review how these changes impact metric calculations. # /reports/data response is now structured by aggregate_by and secondary_aggregate_by Source: https://developer.dashsocial.com/changelog/reports-data-response-structured-by-aggregate-by-and-secondary-aggregate-by ## Changed Response grouping for `GET https://dashboard.dashsocial.com/reports/data` is now controlled by two parameters: * `aggregate_by` sets the primary grouping dimension. Accepted values: ``` TOTAL, BRAND, CHANNEL, ACCOUNT_TAG, TAG, SOURCE_CAMPAIGN, AGE_GENDER, COUNTRY, REGION, PUBLISHER_PLATFORM, FOLLOWER_STATUS, ASSIGNEE, MESSAGE_TAG, MESSAGE_TYPE, SENTIMENT, TOPIC, MEDIA_TYPE, STATE_PROVINCE, CITY, MENTION_TYPE, INDUSTRY, AGE, GENDER, CAMPAIGN, BOARD, GALLERY, CONTENT_TAG ``` * `secondary_aggregate_by` adds an optional second grouping dimension. It is now supported on `report_type=TOTAL_METRIC` and `report_type=GRAPH` (previously stacked bars only). We recommend always including `aggregate_by` in your request. If it is omitted, the endpoint falls back to a default that depends on the report type and the brands and channels in your request, so the grouping may not be what you want. | Report type | Default `aggregate_by` | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `STACKED_BAR_METRIC` | `BRAND` | | `GRAPH` types | `CHANNEL` if more than one channel is requested; otherwise `BRAND` if more than one brand is requested; otherwise `TOTAL` | | Other types (e.g. `TOTAL_GROUPED_METRIC`) | the first available breakdown, usually `CHANNEL` | ## What you need to update 1. Set `aggregate_by` to the grouping your report needs. For a brand-and-channel breakdown, use `aggregate_by=BRAND` and `secondary_aggregate_by=CHANNEL`. 2. Read metrics from each entry. The path matches your grouping: * With `secondary_aggregate_by`: `data[]["breakdowns"][]["metrics"][""][""]` * Without it, the `breakdowns` level is dropped: `data[]["metrics"][""][""]` `` is the channel name when the data is split by channel, otherwise `ALL_CHANNELS`. ## Response structure: TOTAL\_METRIC ```jsonc theme={null} { "data": { "1": { // brand id "avatar": "...", "data_type": "BRAND", "name": "Test Brand", "permissions": { ... }, "user_has_access": true, "breakdowns": { // metric data lives here "FACEBOOK": { "data_type": "CHANNEL", "name": "Facebook", "metrics": { "TOTAL_ENGAGEMENTS": { "FACEBOOK": { "value": 3440.0 } }, "TOTAL_REACH": { "FACEBOOK": { "value": 130303.0 } } } }, "INSTAGRAM": { "metrics": { "TOTAL_ENGAGEMENTS": { "INSTAGRAM": { "value": 12228.0 } }, "TOTAL_REACH": { "INSTAGRAM": { "value": 369475.0 } } } } } }, "2": { ... }, // another brand, same shape "metrics": { "TOTAL_ENGAGEMENTS": { "ALL_CHANNELS": { "value": 23178.0 } }, "TOTAL_REACH": { "ALL_CHANNELS": { "value": 658241.0 } } } } } ``` For `TOTAL_METRIC`, the innermost object is a single `value`. ## Response structure: GRAPH ```jsonc theme={null} { "data": { "1": { // brand id "avatar": "...", "data_type": "BRAND", "name": "Test Brand", "permissions": { ... }, "user_has_access": true, "breakdowns": { // metric data lives here "FACEBOOK": { "data_type": "CHANNEL", "name": "Facebook", "metrics": { "TOTAL_ENGAGEMENTS": { "FACEBOOK": { "2026-05-06": 106.0, "2026-06-01": 1055.0 } }, "TOTAL_REACH": { "FACEBOOK": { "2026-05-06": 5359.0, "2026-06-01": 29441.0 } } } }, "INSTAGRAM": { "metrics": { "TOTAL_ENGAGEMENTS": { "INSTAGRAM": { "2026-05-03": 1109.0, "2026-06-03": 11.0 } }, "TOTAL_REACH": { "INSTAGRAM": { "2026-05-03": 19631.0, "2026-06-03": 26183.0 } } } } } }, "2": { ... }, // another brand, same shape "metrics": { "TOTAL_ENGAGEMENTS": { "ALL_CHANNELS": { "2026-05-03": 1109.0 } }, "TOTAL_REACH": { "ALL_CHANNELS": { "2026-05-03": 19631.0 } } } } } ``` For `GRAPH`, the innermost object is keyed by date. ## Notes A brand only includes a channel under `breakdowns` if it has data for that channel. In the examples above, brand 2 returns Instagram only. The two report types share the same structure. Only the innermost object differs: date-keyed values for `GRAPH`, a single `value` for `TOTAL_METRIC`. # Get campaign performance data Source: https://developer.dashsocial.com/guides/campaigns/get-campaign-performance-data Retrieve campaign details and KPIs across all channels using the Campaigns API. This guide shows you how to use the Campaigns API to retrieve campaign details and KPIs across all channels. Campaigns in Dash Social unify owned, earned, and creator content into a single cross-channel view for holistic measurement. ## Use case examples Pull topline KPIs for a product launch campaign to measure total reach, engagements, and video views across all channels. Fetch UGC content associated with a campaign to quantify earned media alongside owned posts. List all campaigns to compare topline metrics across multiple initiatives (e.g., Spring 2026 vs. Spring 2025). ## Before you start Make sure you have: * **API access token** with permissions to the relevant brand. * **Brand ID** for the account you want to query. See [API Quickstart](/guides/get-started/quickstart) for more details. ## Implementation ### Step 1: Retrieve all campaigns Fetch the full list of campaigns for a brand. Use the returned `id` values to query individual campaigns in subsequent steps. ```http theme={null} GET https://library-backend.dashsocial.com/brands/{brand_id}/campaigns ``` #### Key path parameters * `brand_id`: Your brand's unique ID. Sample Response: ```json theme={null} { "data": [ { "id": 4, "brand_id": 144, "name": "Ryan Test - Easter", "start_date": null, "end_date": null, "number_of_media": 118, "avg_engagement_rate": 0.254018, "total_engagements": 262, "total_impressions": 4154, "total_video_views": 2233, "total_clicks": 6, "included_media_sources": [ "FACEBOOK", "INSTAGRAM", "INSTAGRAM_STORY", "PINTEREST", "TWITTER", "YOUTUBE" ], "included_creator_sources": [ "INSTAGRAM", "YOUTUBE", "TIKTOK" ], "hashtags": [ { "hashtag_id": 3028, "name": "france" } ], "created_at": "2026-04-13T11:46:52+00:00", "updated_at": "2026-03-18T19:56:44+00:00" } ] } ``` #### Key response fields | Field | Description | | -------------------------- | ---------------------------------------------------------------------------------------------- | | `id` | Campaign ID — use this in subsequent API calls | | `name` | Campaign name | | `start_date` / `end_date` | Campaign date range (`null` if not set) | | `number_of_media` | Total posts added to the campaign | | `avg_engagement_rate` | Average engagement rate across all channels | | `total_engagements` | Sum of all engagements across channels | | `total_impressions` | Sum of all impressions across channels | | `total_video_views` | Sum of all video views across channels | | `total_clicks` | Sum of all link clicks across channels | | `included_media_sources` | Owned channels included in this campaign | | `included_creator_sources` | Creator channels included in this campaign | | `hashtags` | Hashtags tracked in this campaign (for performance tracking only — does not auto-pull content) | *** ### Step 2: Retrieve a specific campaign Fetch the full details for a single campaign by its ID. ```http theme={null} GET https://library-backend.dashsocial.com/brands/{brand_id}/campaigns/{campaign_id} ``` #### Key path parameters * `brand_id`: Your brand's unique ID. * `campaign_id`: The campaign ID from Step 1. Sample Response: ```json theme={null} { "id": 61237, "brand_id": 144, "name": "2026 Fall Season Launch", "start_date": "2026-09-01T00:00:00+00:00", "end_date": "2026-10-15T23:59:59+00:00", "number_of_media": 75, "avg_engagement_rate": 0.0858496, "avg_engagements": 2.33333, "total_engagements": 175, "total_impressions": 4682, "total_video_views": 836, "total_clicks": 3, "has_ugc": true, "included_media_sources": [ "FACEBOOK", "INSTAGRAM", "PINTEREST", "TIKTOK", "TWITTER", "YOUTUBE" ], "included_creator_sources": [], "hashtags": [], "topline_metrics": { "OWNED_SUMMARY": [ { "goal": null, "metric": "video_views_v2", "source": "campaign_stats" }, { "goal": null, "metric": "engagements", "source": "campaign_stats" }, { "goal": null, "metric": "avg_engagement_rate", "source": "campaign_stats" }, { "goal": null, "metric": "impressions_v2", "source": "campaign_stats" }, { "goal": null, "metric": "link_clicks", "source": "campaign_stats" } ] }, "created_at": "2026-12-10T20:33:21+00:00", "updated_at": "2026-03-18T19:57:20+00:00" } ``` #### Key response fields | Field | Description | | ------------------------ | --------------------------------------------------------------- | | `topline_metrics` | Configured summary metrics and optional goals for this campaign | | `has_ugc` | Whether UGC content has been added to the campaign | | `included_media_sources` | Owned channels contributing to campaign data | *** ### Step 3: Retrieve campaign media Fetch owned posts associated with a campaign, filtered by channel and date range. ```http theme={null} GET https://library-backend.dashsocial.com/brands/{brand_id}/campaigns/{campaign_id}/media ``` #### Key query parameters | Parameter | Required | Description | | ----------------------------- | -------- | ------------------------------------------------------------------------ | | `source` | Yes | Channel to filter by. Repeat the parameter to include multiple channels. | | `source_created_on_or_after` | Yes | Start date filter (`YYYY-MM-DD`) | | `source_created_on_or_before` | Yes | End date filter (`YYYY-MM-DD`) | | `sort` | No | Sort order. Use `DATE` to sort by publish date (default). | | `limit` | No | Number of results per page. Max `99`. | | `offset` | No | Pagination offset. | #### Available `source` values `INSTAGRAM`, `PINTEREST`, `FACEBOOK`, `INSTAGRAM_STORY`, `TWITTER`, `TIKTOK`, `YOUTUBE`, `LIKESHOP`, `TIKTOK_LIKESHOP`, `RELATIONSHIPS`, `UGC`, `CREATORS_INSTAGRAM`, `CREATORS_INSTAGRAM_STORIES` Example request for Facebook posts: ```http theme={null} GET https://library-backend.dashsocial.com/brands/144/campaigns/61237/media?source=FACEBOOK&source_created_on_or_after=2026-01-01&source_created_on_or_before=2026-03-01&sort=DATE&limit=99&offset=0 ``` Sample Response: ```json theme={null} { "data": [ { "id": 618008202, "brand_id": 144, "source": "FACEBOOK", "source_type": "OWNED", "type": "VIDEO", "source_id": "178420822757236_1985966815568805", "source_created_at": "2026-12-10T19:49:04", "collections": { "campaigns": [61237] }, "facebook": { "message": "gif", "type": "video", "url": "https://www.facebook.com/1014506099381553/videos/878590275119927", "page_name": "Sunny Today", "organic_reach": 5, "organic_video_views": 3, "organic_engagements": 0, "organic_engagement_rate": 0.0, "organic_impressions": 0, "organic_link_clicks": 0, "paid_and_organic_reach": 5, "paid_and_organic_video_views": 3, "paid_and_organic_engagements": 0, "paid_and_organic_impressions": 0 } } ], "paging": { "count": 1, "next": null, "previous": null } } ``` #### Key response fields | Field | Description | | ------------------------------------------ | ------------------------------------------------------------------------------- | | `source` | The channel this post belongs to | | `source_type` | `OWNED` for brand-posted content | | `type` | Media type: `IMAGE`, `VIDEO`, `CAROUSEL` | | `facebook` / `instagram` / `tiktok` / etc. | Platform-specific metrics object — only the relevant channel field is populated | **Pagination:** Use `paging.next` to detect additional pages, and increment `offset` by your `limit` value to retrieve them. *** ### Step 4: Retrieve campaign UGC Fetch user-generated content associated with a campaign. ```http theme={null} GET https://library-backend.dashsocial.com/brands/{brand_id}/campaigns/{campaign_id}/ugc ``` #### Key query parameters | Parameter | Required | Description | | ----------------------------- | -------- | ----------------------------------------------- | | `type` | Yes | UGC type filter. | | `source_created_on_or_after` | Yes | Start date filter (`YYYY-MM-DD`) | | `source_created_on_or_before` | Yes | End date filter (`YYYY-MM-DD`) | | `sort` | No | Sort order. Use `DATE` to sort by publish date. | | `limit` | No | Number of results per page. Max `99`. | | `offset` | No | Pagination offset. | #### Available `type` values | Value | Description | | ----------- | ---------------------------------------- | | `MENTIONED` | Posts where your brand was @mentioned | | `TAGGED` | Posts where your brand was photo-tagged | | `ANY` | Either mentioned or tagged | | `ALL` | All UGC regardless of mention/tag status | Example request: ```http theme={null} GET https://library-backend.dashsocial.com/brands/144/campaigns/61237/ugc?type=MENTIONED&source_created_on_or_after=2026-01-01&source_created_on_or_before=2026-03-01&sort=DATE&limit=99&offset=0 ``` Sample Response: ```json theme={null} { "data": [ { "id": 617880518, "brand_id": 144, "source": "INSTAGRAM", "source_type": "UGC", "type": "IMAGE", "source_created_at": "2026-12-10T15:02:56", "collections": { "campaigns": [61237] }, "instagram": { "caption": "for u @sunny.today", "url": "https://www.instagram.com/p/DSFlan1APDu/", "is_mentioned": true, "is_tagged": false, "like_count": 2, "comments_count": 0, "engagements_public": 2, "engagement_rate_public": 0.2222222222222222, "reach": 1, "emv": 302.43 }, "instagram_user": { "handle": "_flapjackie", "followers": 8, "is_business": 1 } } ], "paging": { "count": 1, "next": null, "previous": null } } ``` #### Key response fields | Field | Description | | -------------------------------------- | ---------------------------------------- | | `source_type` | Always `UGC` for this endpoint | | `instagram.is_mentioned` / `is_tagged` | How this post relates to your brand | | `instagram.emv` | Estimated Media Value for this UGC post | | `instagram_user` | Creator profile info (handle, followers) | *** ### Step 5: Retrieve campaign statistics Fetch aggregated daily statistics broken down by channel for a campaign. This powers the time-series charts in the Campaign Summary. ```http theme={null} GET https://library-backend.dashsocial.com/brands/{brand_id}/campaigns/{campaign_id}/stats ``` #### Key path parameters * `brand_id`: Your brand's unique ID. * `campaign_id`: The campaign ID from Step 1. Sample Response: ```json theme={null} { "data": { "2026-11-28": { "FACEBOOK": { "number_of_media": 1.0, "number_of_videos": 1.0, "avg_engagement_rate": 0.0, "avg_reach": 5.0, "engagements": 1.0, "impressions": 0.0, "total_video_views": 4.0, "video_views": 4.0, "views": 16.0, "link_clicks": 0.0 }, "INSTAGRAM": { "number_of_media": 0.0 }, "INSTAGRAM_STORY": { "number_of_media": 0.0 }, "PINTEREST": { "number_of_media": 0.0 }, "TIKTOK": { "number_of_media": 0.0 }, "TWITTER": { "number_of_media": 0.0 }, "UGC": { "number_of_media": 0.0 }, "YOUTUBE": { "number_of_media": 0.0 } }, "2026-12-05": { "FACEBOOK": { "number_of_media": 2.0, "avg_engagement_rate": 0.0, "avg_reach": 4.0, "engagements": 1.0, "impressions": 0.0, "link_clicks": 0.0, "views": 12.0 }, "INSTAGRAM": { "number_of_media": 1.0, "number_of_videos": 1.0, "avg_engagement_rate": 0.0, "avg_reach": 1.0, "engagements": 0.0, "impressions": 0.0, "video_views": 0.0, "views": 5.0 }, "TIKTOK": { "number_of_media": 1.0, "avg_engagement_rate": 0.0, "avg_reach": 2.0, "avg_retention_rate": 0.340816, "engagements": 0.0, "fyp_views_percentage": 0.333, "video_views": 3.0 }, "INSTAGRAM_STORY": { "number_of_media": 0.0 }, "PINTEREST": { "number_of_media": 0.0 }, "TWITTER": { "number_of_media": 0.0 }, "UGC": { "number_of_media": 0.0 }, "YOUTUBE": { "number_of_media": 0.0 } }, "2026-12-09": { "FACEBOOK": { "number_of_media": 1.0, "number_of_videos": 1.0, "avg_engagement_rate": 0.0, "avg_reach": 4.0, "engagements": 0.0, "impressions": 0.0, "total_video_views": 1.0, "video_views": 1.0, "views": 1.0 }, "INSTAGRAM": { "number_of_media": 4.0, "avg_engagement_rate": 0.014880975, "avg_reach": 7.25, "engagements": 5.0, "impressions": 0.0, "views": 129.0 }, "TIKTOK": { "number_of_media": 3.0, "avg_engagement_rate": 0.013333333333333334, "avg_reach": 83.33333333333333, "avg_retention_rate": 0.10478543333333333, "engagements": 5.0, "fyp_views_percentage": 0.9743333333333334, "video_views": 274.0 }, "TWITTER": { "number_of_media": 1.0, "avg_engagement_rate": 0.0, "engagements": 0.0, "impressions": 2.0 }, "UGC": { "number_of_media": 1.0, "avg_engagement_rate": 0.0, "engagements": 0.0, "estimated_reach": 7.0, "mentions": 0.0, "people_tags": 1.0 }, "INSTAGRAM_STORY": { "number_of_media": 0.0 }, "PINTEREST": { "number_of_media": 0.0 }, "YOUTUBE": { "number_of_media": 0.0 } }, "2026-12-10": { "FACEBOOK": { "number_of_media": 2.0, "number_of_videos": 2.0, "avg_engagement_rate": 0.0, "avg_reach": 4.0, "engagements": 0.0, "impressions": 0.0, "total_video_views": 4.0, "video_views": 4.0, "views": 22.0, "link_clicks": 0.0 }, "INSTAGRAM": { "number_of_media": 1.0, "avg_engagement_rate": 0.222222, "avg_reach": 1.0, "engagements": 2.0, "impressions": 0.0, "views": 8.0 }, "PINTEREST": { "number_of_media": 19.0, "number_of_videos": 2.0, "avg_engagement_rate": 0.0045715863157894734, "engagements": 128.0, "impressions": 3800.0, "link_clicks": 0.0, "saves": 11.0, "video_views": 304.0 }, "TIKTOK": { "number_of_media": 1.0, "avg_engagement_rate": 0.0, "avg_reach": 2.0, "avg_retention_rate": 0.05, "engagements": 0.0, "fyp_views_percentage": 0.0, "video_views": 4.0 }, "TWITTER": { "number_of_media": 1.0, "avg_engagement_rate": 1.0, "engagements": 3.0, "impressions": 3.0 }, "UGC": { "number_of_media": 2.0, "avg_engagement_rate": 0.444444, "engagements": 8.0, "estimated_reach": 92.0, "mentions": 1.0, "people_tags": 1.0 }, "YOUTUBE": { "number_of_media": 2.0, "avg_view_duration": 0.0, "engagements": 0.0, "likes": 0.0, "video_views": 0.0, "watch_time": 0.0 }, "INSTAGRAM_STORY": { "number_of_media": 0.0 } } } } ``` #### Response structure The response is a dictionary keyed by **date** (`YYYY-MM-DD`). Each date contains a breakdown by channel. Only dates on which posts were published are returned — dates with no activity are omitted. #### Key metrics by channel | Channel | Key Metrics | | ----------------- | ------------------------------------------------------------------------------------------------- | | `INSTAGRAM` | `engagements`, `avg_engagement_rate`, `impressions`, `views`, `video_views` | | `FACEBOOK` | `engagements`, `avg_engagement_rate`, `avg_reach`, `video_views`, `views`, `link_clicks` | | `TIKTOK` | `video_views`, `engagements`, `avg_engagement_rate`, `avg_retention_rate`, `fyp_views_percentage` | | `PINTEREST` | `engagements`, `impressions`, `saves`, `video_views`, `link_clicks` | | `TWITTER` | `engagements`, `impressions`, `avg_engagement_rate` | | `YOUTUBE` | `video_views`, `watch_time`, `engagements`, `avg_view_duration` | | `UGC` | `engagements`, `avg_engagement_rate`, `estimated_reach`, `mentions`, `people_tags` | | `INSTAGRAM_STORY` | `impressions`, `exits`, `link_clicks`, `avg_completion_rate` | Channels with `number_of_media: 0` on a given date had no posts published that day. Metric fields for those channels will be `null`. # Integrate Community Data with Your Customer Service Platform Source: https://developer.dashsocial.com/guides/community/integrate-community-data-with-your-customer-service-platform Use the Community API to retrieve, filter, and reply to social media messages and comments, and track sentiment across platforms. The Community API lets you sync social media conversations with your customer service platform. This guide covers: * Retrieving and replying to direct messages across Instagram, Facebook, and X * Retrieving and replying to comments across Facebook, Instagram, TikTok, and YouTube * Analyzing sentiment distribution and trends over time **API update:** DMs have moved from conversation-level to message-level interactions. `GET /community_interactions` now returns one result per message instead of per conversation. See the [migration changelog](/changelog/community-api-migrate-dms-to-message-level-interactions) for full details. ## Use cases Customer service teams use the Community API to connect social conversations directly into their support workflows. Filter DMs by keyword to surface complaints and automatically route them to the right support queue in Zendesk or Salesforce. Pull comments across Facebook and Instagram posts to review, tag, and respond without leaving your existing tooling. Track positive and negative sentiment trends over time to catch issues early and measure the impact of campaigns or product launches. ## Before you start Make sure you have: * **API access token** with permissions to the relevant brand. * **Brand ID** for the account you want to query. See [API Quickstart](/guides/get-started/quickstart) for more details. *** ## Use Case 1: Retrieve and Respond to Direct Messages Filter DMs by platform, keyword, and date range to surface messages that need attention, then reply directly through the API. ### Step 1: Retrieve DMs `GET /community_interactions` returns a list of individual messages. Each result is a single message with its content in `text` and a `conversation_id` linking it to the thread it belongs to. See the [Get Community Interactions](/api-reference/community/community-interactions/get-community-interactions) endpoint reference for the full parameter list. **Parameters** | Parameter | Description | | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `brand_id` | **Required.** The brand to query. | | `types` | Filter by interaction type. Use `,` as OR for multiple types. **DMs:** `INSTAGRAM_CONVERSATION`, `FACEBOOK_CONVERSATION`, `TWITTER_CONVERSATION`, `COMMUNITY_INTERACTION` | | `source_updated_after` / `source_updated_before` | Date range filter. ISO 8601 format. Time is optional: `2024-08-15` and `2024-08-15T00:00:00-04:00` are both valid. | | `message_nested_date_filter` | Set to `true` to narrow results to threads where keyword matches fall within the date range. | | `query` | Keyword filter. Use `,` as OR for multiple keywords. | | `sort` | Sort order. `-SOURCE_UPDATED_AT` (most recently updated first), `SOURCE_UPDATED_AT` (oldest first), `RELEVANCE`, `SAMPLE` (random sample, only valid for `COMMUNITY_INTERACTION` type) | | `is_closed` | Set to `false` to exclude closed interactions. | | `limit` | Number of results to return. Maximum `100` to avoid rate limiting. | | `offset` | Pagination offset. | ```http theme={null} GET https://community.dashsocial.com/community_interactions ?brand_id= &types=INSTAGRAM_CONVERSATION &source_updated_after=2024-08-15T00:00:00-04:00 &source_updated_before=2024-09-05T23:59:59-04:00 &message_nested_date_filter=true &sort=-SOURCE_UPDATED_AT &query=issue,not working,don't like &is_closed=false &limit=99 &offset=0 ``` Response example: ```json theme={null} { "data": [ { "brand_id": "", "conversation_id": 1027220732, "created_at": "2024-09-05T21:08:07.010000", "id": 263350682, "is_closed": false, "tag_ids": [15307], "text": "I don't like sunny today", "type": "INSTAGRAM_CONVERSATION", "updated_at": "2024-09-05T21:08:10" } ], "paging": { "count": 7, "next": null, "offset": null, "previous": null } } ``` `INSTAGRAM_CONVERSATION` includes story replies and story mentions, not just direct messages. Check the `story_reply` and `story_mention` fields in the full thread (Step 2) to distinguish them. ### Step 2: Get the Full Thread (optional) If you need the full message history for a conversation, use the `conversation_id` from Step 1. This step is optional — message content is already available in `text` from Step 1. See the [Get Interaction Messages](/api-reference/community/community-interactions/get-interaction-messages) endpoint reference. ```http theme={null} GET https://community.dashsocial.com/conversations/{conversation_id} ``` Response example: ```json theme={null} { "data": [ { "conversation_id": 1027220732, "created_at": "2024-09-05T21:08:10", "from_participant_id": "", "id": 263350682, "send_failed": false, "text": "I don't like sunny today", "to_participant_id": 17841402247948351, "type": "INSTAGRAM_CONVERSATION", "updated_at": "2024-09-05T21:08:10" } ], "paging": { "count": 13, "next": null, "previous": null } } ``` ### Step 3: Reply to a Conversation Send a reply using the `conversation_id` from Step 1. Instagram and Facebook do not allow replies to DMs received more than 7 days ago through third-party platforms. ```http theme={null} POST https://community.dashsocial.com/conversations/{conversation_id}/messages { "text": "Hello! Is there anything we can help with?" } ``` *** ## Use Case 2: Retrieve and Respond to Comments Use the same `GET /community_interactions` endpoint to retrieve comments across platforms, then reply to them directly through the API. ### Step 1: Retrieve Comments Filter by `types` to pull comments across platforms. Use the same parameters as [Use Case 1](#step-1-retrieve-dms). The only difference is the `types` values. See the [Get Community Interactions](/api-reference/community/community-interactions/get-community-interactions) endpoint reference for the full parameter list. | Type | Description | | ----------------------------------------------------------------------------------------------- | ---------------------------------- | | `FACEBOOK_COMMENT`, `INSTAGRAM_COMMENT`, `TIKTOK_COMMENT`, `TWITTER_RETWEET`, `YOUTUBE_COMMENT` | Organic comments across platforms. | | `FACEBOOK_ADS_COMMENT`, `INSTAGRAM_ADS_COMMENT` | Comments on paid ad posts. | ```http theme={null} GET https://community.dashsocial.com/community_interactions ?brand_id= &types=INSTAGRAM_COMMENT,FACEBOOK_COMMENT,TIKTOK_COMMENT,YOUTUBE_COMMENT &source_updated_after=2024-08-15 &source_updated_before=2024-09-05 &sort=-SOURCE_UPDATED_AT &is_closed=false &limit=99 &offset=0 ``` Each result includes an `id` you'll use to reply in Step 2, and platform-specific comment identifiers (e.g. `facebook_comment_id`) in the full comment detail. If you need comments scoped to a single post, use the platform-specific comment endpoints with a `media_id`. First get the post's `id` from the Library API, then pass it as `media_id`. ```http theme={null} PUT https://library-backend.dashsocial.com/brands//media/v2 { "filters": { "source_created_at": { "start": "2024-08-14", "end": "2024-08-31" }, "brand_media_types": ["FACEBOOK_OWNED"] }, "limit": 99, "offset": 0 } ``` Then fetch comments for that post: ```http theme={null} GET https://community.dashsocial.com/facebook_comments ?media_id= &brand_id= ``` Replace `facebook_comments` with `instagram_comments`, `tweets`, `tiktok_comments`, or `youtube_comments` for other platforms. See the endpoint references for [Facebook comments](/api-reference/community/facebook-comments/get-facebook-comments), [Instagram comments](/api-reference/community/instagram-comments/get-instagram-comments), [TikTok comments](/api-reference/community/tiktok-comments/get-tiktok-comments), and [YouTube comments](/api-reference/community/youtube-comments/get-youtube-comments). ### Step 2: Reply to Comments Use the `facebook_comment_id` (or platform equivalent) from Step 1 as `parent_comment_id` to thread the reply under the original comment. Facebook does not allow replies to comments received more than 7 days ago through third-party platforms. ```http theme={null} POST https://community.dashsocial.com/facebook_comments { "brand_id": "", "parent_comment_id": "", "text": "Thank you!" } ``` Replace `facebook_comments` with `instagram_comments`, `tweets`, `tiktok_comments`, or `youtube_comments` for other platforms. Response example: ```json theme={null} { "brand_id": "", "brand_user_reply": { "brand_id": "", "created_at": "2024-09-04T16:34:28", "id": 501004, "resource_id": 1205650847, "resource_type": "FACEBOOK_COMMENT", "updated_at": "2024-09-04T16:34:28", "user_id": 114999 }, "created_at": "2024-09-04T16:34:28+00:00", "facebook_comment_id": "1574406790058145_824658966449828", "facebook_parent_comment_id": "1574406790058145_438078445927408", "id": 1205650847, "is_owned": true, "text": "Thank you!", "type": "FACEBOOK_COMMENT", "updated_at": "2024-09-04T16:34:28+00:00" } ``` *** ## Use Case 3: Analyze Community Sentiment Track interaction volume, sentiment, and top keywords across platforms. All endpoints support multiple brands in a single request. ### Sentiment Distribution `POST /sentiment_distribution_stats` returns the positive, neutral, and negative breakdown for a brand's interactions. Filter by date range, platform type, and other attributes. See the [Get Sentiment Distribution Stats](/api-reference/community/community-overview-v2/create-sentiment-distribution-stats) endpoint reference. **Step 1: Map Your Parameters** | Parameter | Description | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | | `brand_ids` | **Required.** One or more brand IDs. Pass multiple to analyze across brands at once: `[144, 145, 146]`. | | `source_updated_after` / `source_updated_before` | Date range for the interactions. ISO 8601 format. | | `types` | Filter by interaction type. Same values as `GET /community_interactions`. | | `is_positive` / `is_negative` / `is_neutral` | Filter to interactions with a specific sentiment label. | | `is_closed` | Filter by closed status. | | `query` | Keyword filter. | | `tag_ids` | Filter by interaction tag IDs (AND condition). | **Step 2: Make the API Call** ```http theme={null} POST https://community.dashsocial.com/sentiment_distribution_stats { "brand_ids": [144], "source_updated_after": "2024-08-01T00:00:00Z", "source_updated_before": "2024-08-31T23:59:59Z", "types": ["INSTAGRAM_COMMENT", "FACEBOOK_COMMENT"] } ``` Response returns a `data` object with sentiment counts broken down per platform. *** ### Sentiment Time Series `POST /sentiment_time_series` returns per-platform sentiment data over time. Use this to chart sentiment trends across a date range. See the [Get Sentiment Time Series](/api-reference/community/community-overview-v2/create-sentiment-time-series) endpoint reference. **Step 1: Map Your Parameters** | Parameter | Description | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | | `brand_ids` | **Required.** One or more brand IDs. Pass multiple to analyze across brands at once: `[144, 145, 146]`. | | `source_updated_after` / `source_updated_before` | Date range for the time series. ISO 8601 format. | | `scale` | Time series granularity: `DAY`, `HOUR`, `WEEK`, `MONTH`, `QUARTER`. | | `types` | Filter by interaction type. Same values as `GET /community_interactions`. | | `is_closed` | Filter by closed status. | | `query` | Keyword filter. | | `tag_ids` | Filter by interaction tag IDs (AND condition). | **Step 2: Make the API Call** ```http theme={null} POST https://community.dashsocial.com/sentiment_time_series { "brand_ids": [144], "source_updated_after": "2024-08-01T00:00:00Z", "source_updated_before": "2024-08-31T23:59:59Z", "scale": "DAY", "types": ["INSTAGRAM_COMMENT", "FACEBOOK_COMMENT"] } ``` Response returns a `data` object with per-platform sentiment counts indexed by date. *** ### Volume Time Series `POST /volume_time_series` returns interaction volume over time, broken down by interaction type per date. Use this to track how many comments, messages, and mentions your brand receives across platforms. DM messages are now included in volume calculations. If your brand has active DMs, expect higher counts compared to previous results. See the [Get Volume Time Series](/api-reference/community/community-overview-v2/create-volume-time-series) endpoint reference. **Step 1: Map Your Parameters** | Parameter | Description | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | | `brand_ids` | **Required.** One or more brand IDs. Pass multiple to analyze across brands at once: `[144, 145, 146]`. | | `source_updated_after` / `source_updated_before` | Date range filter. ISO 8601 format. Time is optional: `2024-08-15` and `2024-08-15T00:00:00-04:00` are both valid. | | `scale` | Time series granularity: `DAY`, `HOUR`, `WEEK`, `MONTH`, `QUARTER`. | | `types` | Filter by interaction type. Same values as `GET /community_interactions`. | | `is_closed` | Filter by closed status. | | `query` | Keyword filter. | | `tag_ids` | Filter by interaction tag IDs (AND condition). | **Step 2: Make the API Call** ```http theme={null} POST https://community.dashsocial.com/volume_time_series { "brand_ids": [144], "source_updated_after": "2024-08-01T00:00:00Z", "source_updated_before": "2024-08-31T23:59:59Z", "scale": "DAY", "types": ["INSTAGRAM_COMMENT", "FACEBOOK_COMMENT"] } ``` Response example: ```json theme={null} { "data": { "2026-02-06": { "facebook_comment": 4, "facebook_message": 0, "instagram_comment": 0, "instagram_message": 15, "tiktok_comment": 0, "twitter_mention": 6, "twitter_message": 0, "twitter_quote": 2, "twitter_retweet": 4, "youtube_comment": 0, "total": 31 } } } ``` Each key is a date. The value breaks down volume by interaction type, with `total` as the sum across all types for that day. *** ### Top Keywords `POST /top_keywords` returns the most frequent keywords from community interactions, ranked by total mentions. Each keyword includes a sentiment breakdown so you can see whether mentions are positive, neutral, or negative. See the [Get Top Keywords](/api-reference/community/community-overview-v2/create-top-keywords) endpoint reference. **Step 1: Map Your Parameters** | Parameter | Description | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | | `brand_ids` | **Required.** One or more brand IDs. Pass multiple to analyze across brands at once: `[144, 145, 146]`. | | `source_updated_after` / `source_updated_before` | Date range filter. ISO 8601 format. Time is optional: `2024-08-15` and `2024-08-15T00:00:00-04:00` are both valid. | | `types` | Filter by interaction type. Same values as `GET /community_interactions`. | | `query` | Keyword filter to scope results. | | `is_closed` | Filter by closed status. | | `tag_ids` | Filter by interaction tag IDs (AND condition). | **Step 2: Make the API Call** ```http theme={null} POST https://community.dashsocial.com/top_keywords { "brand_ids": [144], "source_updated_after": "2024-08-01T00:00:00Z", "source_updated_before": "2024-08-31T23:59:59Z", "types": ["INSTAGRAM_COMMENT", "FACEBOOK_COMMENT"] } ``` Response example: ```json theme={null} { "data": { "love": { "negative": 3, "neutral": 10, "positive": 30, "total": 43 }, "style": { "negative": 4, "neutral": 6, "positive": 11, "total": 21 }, "order": { "negative": 7, "neutral": 1, "positive": 2, "total": 10 }, "perfect": { "negative": 0, "neutral": 1, "positive": 10, "total": 11 }, "wait": { "negative": 0, "neutral": 0, "positive": 12, "total": 12 } } } ``` Each key is a keyword string. The values show how many interactions containing that keyword were negative, neutral, positive, and the total count. *** ## Limitations * **All channels:** Group DMs are not supported. * **Instagram:** Brands cannot reply to DMs received more than 7 days ago. Deleted comments are not reported back to Dash Social. * **Facebook:** Brands cannot reply to DMs received more than 7 days ago. Deleted comments are not reported back to Dash Social. * **TikTok:** `@mentions` in replies are rendered as plain text without linking to the mentioned profile. * **X (Twitter):** Deleted comments are not reported back to Dash Social. * **YouTube:** Only root-level comments are imported. Replies to comments are not supported. Native emojis are not rendered when replying via the API. # Quickstart Source: https://developer.dashsocial.com/guides/get-started/quickstart Generate an API key, authenticate, and make your first request with the Dash Social API. ## Before You Begin Make sure you meet these requirements: * Your plan includes **API access**. If you're not sure, contact Support. * You're a **brand admin**. Only admins can generate API keys. Ask an admin or your account manager if you need access. *** ## Step 1: Generate an API Key The Dash Social API uses **Bearer tokens** for authentication. Include the token in every request: ```bash theme={null} Authorization: Bearer {token} ``` To create your key: 1. In Dash Social, go to **Settings → API and Integrations → Developers**, or [click here](https://app.dashsocial.com/settings/developer_page). 2. Copy your **Brand ID** — it appears next to your brand name. 3. Click **Generate New API Key** and give your key a name. 4. Copy and save the key securely — **it will only be shown once.** Keep your token secret and never include it in client-side code. Always send API requests through your backend. **Working with multiple brands?** Contact Support if you need a multi-brand API key. *** ## Step 2: Verify Your API Key and Brand Access Once you've generated your API key, use the `/api/self` endpoint to confirm what your token can access. This call returns: * Which **brand(s)** your API key has access to * The **organization** info linked to your brand * A full list of **permissions** and feature access tied to your token This is useful when: * You're unsure which brand ID to use * You want to check if a feature is enabled for your API key * You're debugging why a request is failing due to access restrictions **Endpoint** ```bash theme={null} GET https://auth.dashsocial.com/api/self ``` ```bash theme={null} curl 'https://auth.dashsocial.com/api/self' \ -H 'Authorization: Bearer {token}' ``` **Sample Response** ```json theme={null} { "accessible_brands": [144], "brands": { "sunny-today": { "id": 144, "name": "sunny.today", "organization": { "id": 1, "name": "Dash Social" }, "permissions": { "campaigns": { "can_access_campaigns": true }, "community": { "can_access_community": true, "can_access_community_overview": true }, "library": { "can_access_library": true, "can_access_shoppable_galleries": true } } } }, "permissions": { "..." : "..." }, "organization": { "id": 1, "name": "Dash Social" } } ``` If you don't see an expected brand or permission, double check that your token is still valid in your settings. If issues persist, contact Support. *** ## What's Next Export owned, earned, competitor, and TSI report data via API. Get post performance data across all channels. Get started with shoppable galleries and product feeds. # Rate Limits & Pagination Source: https://developer.dashsocial.com/guides/get-started/rate-limits-pagination Learn how to handle large data sets efficiently and stay within your API request limits. # Overview Learn how Dash Social handles API rate limits and paginated responses. This helps you avoid throttling and reliably fetch large sets of data across multiple requests. # Rate Limits To ensure consistent performance across all users, the Dash Social API enforces rate limits at two levels: * **App-level limit**: Your application can make up to **1000 requests per minute total**. * **Endpoint-level limits**: Some endpoints may have stricter rate limits depending on system load or data sensitivity. Every API response includes headers that show your current usage: ``` x-ratelimit-limit: 1000 # total calls allowed per minute x-ratelimit-remaining: 996 # how many calls you have left x-ratelimit-reset: 1591064298 # time (in UNIX seconds) when your limit resets ``` Use these headers to monitor and manage your request volume dynamically. ## Best Practices * Monitor your headers: Track `x-ratelimit-remaining` to avoid hitting limits. * Cache responses: Reduce repeated API calls when possible. * Back off gracefully: If throttled, retry after the reset time. * Batch your requests: Use pagination instead of pulling all data at once. ## When Limits Are Exceeded If your app exceeds the rate limit, requests will return an error and be temporarily throttled. Wait until the `x-ratelimit-reset` time before sending new requests. *** # Pagination When fetching large collections - such as media, boards, or scheduled posts - the Dash Social API returns results in **pages**. Each "list" endpoint includes a standard `paging` object in the response: ```json theme={null} { "paging": { "count": 1156, "previous": "https://library-backend.dashsocial.com/brands/{brand_id}/media/v2?limit=10&offset=0", "next": "https://library-backend.dashsocial.com/brands/{brand_id}/media/v2?limit=10&offset=10" }, "data": [ { ... } ] } ``` ## How it works * The data array contains the current page of results. * The next and previous fields provide full URLs for the next and previous pages. * If next is null, you've reached the end of the results. ## Parameters You can control how many results are returned per request using **`limit`** and **`offset`**. | Parameter | Type | Description | | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `limit` | integer | The number of results to return per request (e.g., `limit=10`). The default and maximum values may vary by endpoint. | | `offset` | integer | The number of results to skip before starting to return data. Use this to move through pages (e.g., `offset=10` skips the first 10 results). | ## Example Fetch the first 10 media items: ``` curl 'https://library-backend.dashsocial.com/brands/{brand_id}/media/v2?limit=10' \ -H 'Authorization: Bearer {token}' ``` Then use the "next" URL from the response to get the next page: ``` curl 'https://library-backend.dashsocial.com/brands/{brand_id}/media/v2?limit=10&offset=10' \ -H 'Authorization: Bearer {token}' ``` # BigQuery: Facebook Owned Metrics Schema Source: https://developer.dashsocial.com/guides/integration/connect-bigquery-to-dash-social/bigquery-facebook-schema ```json theme={null} { "schema": { "fields": [ { "name": "DATA_SYNC_TIME", "type": "DATETIME" }, { "name": "REPORTING_PERIOD_START_DATE", "type": "DATE" }, { "name": "REPORTING_PERIOD_END_DATE", "type": "DATE" }, { "name": "REPORTING_PERIOD_IN_DAYS", "type": "INTEGER" }, { "name": "AVG_REACH", "type": "FLOAT" }, { "name": "AVG_EFFECTIVENESS", "type": "FLOAT" }, { "name": "AVG_ENGAGEMENT_RATE", "type": "FLOAT" }, { "name": "COMMENTS", "type": "FLOAT" }, { "name": "LINK_CLICKS", "type": "FLOAT" }, { "name": "NUMBER_OF_POSTS", "type": "FLOAT" }, { "name": "OTHER_CLICKS", "type": "FLOAT" }, { "name": "FOLLOWER_GROWTH_RATE", "type": "FLOAT" }, { "name": "NET_NEW_FOLLOWERS", "type": "FLOAT" }, { "name": "TOTAL_FOLLOWERS", "type": "FLOAT" }, { "name": "PAGE_REACH", "type": "FLOAT" }, { "name": "PHOTO_VIEW_CLICKS", "type": "FLOAT" }, { "name": "POST_CLICKS", "type": "FLOAT" }, { "name": "IMPRESSIONS_BY_POST", "type": "FLOAT" }, { "name": "REACTIONS", "type": "FLOAT" }, { "name": "SHARES", "type": "FLOAT" }, { "name": "TOTAL_ENGAGEMENTS", "type": "FLOAT" }, { "name": "VIDEO_COMPLETE_VIEWS", "type": "FLOAT" }, { "name": "VIDEO_VIEWS", "type": "FLOAT" }, { "name": "COMMENT_SENTIMENT_POSITIVE_RATE", "type": "FLOAT" }, { "name": "COMMENT_SENTIMENT_NEUTRAL_RATE", "type": "FLOAT" }, { "name": "COMMENT_SENTIMENT_NEGATIVE_RATE", "type": "FLOAT" } ] } } ``` # BigQuery: TikTok Owned Metrics Schema Source: https://developer.dashsocial.com/guides/integration/connect-bigquery-to-dash-social/bigquery-tiktok-schema ```json theme={null} { "schema": { "fields": [ { "name": "DATA_SYNC_TIME", "type": "DATETIME" }, { "name": "REPORTING_PERIOD_START_DATE", "type": "DATE" }, { "name": "REPORTING_PERIOD_END_DATE", "type": "DATE" }, { "name": "REPORTING_PERIOD_IN_DAYS", "type": "INTEGER" }, { "name": "NUMBER_OF_POSTS", "type": "FLOAT" }, { "name": "NET_NEW_FOLLOWERS", "type": "FLOAT" }, { "name": "TOTAL_FOLLOWERS", "type": "FLOAT" }, { "name": "FOLLOWER_GROWTH_RATE", "type": "FLOAT" }, { "name": "ENGAGEMENTS", "type": "FLOAT" }, { "name": "VIDEO_VIEWS", "type": "FLOAT" }, { "name": "ORGANIC_LIKES", "type": "FLOAT" }, { "name": "ORGANIC_COMMENTS", "type": "FLOAT" }, { "name": "SHARES", "type": "FLOAT" }, { "name": "PROFILE_VIEWS", "type": "FLOAT" }, { "name": "TOTAL_VIDEO_VIEWS", "type": "FLOAT" }, { "name": "TOTAL_LIKES", "type": "FLOAT" }, { "name": "AVG_TOTAL_LIKES", "type": "FLOAT" }, { "name": "TOTAL_COMMENTS", "type": "FLOAT" }, { "name": "AVG_TOTAL_COMMENTS", "type": "FLOAT" }, { "name": "TOTAL_SHARES", "type": "FLOAT" }, { "name": "AVG_TOTAL_SHARES", "type": "FLOAT" }, { "name": "TOTAL_ENGAGEMENTS", "type": "FLOAT" }, { "name": "AVG_TOTAL_ENGAGEMENTS", "type": "FLOAT" }, { "name": "AVG_REACH", "type": "FLOAT" }, { "name": "AVG_ENGAGEMENT_RATE", "type": "FLOAT" }, { "name": "AVG_RETENTION_RATE", "type": "FLOAT" }, { "name": "AVG_FYP_VIEWS", "type": "FLOAT" }, { "name": "AVG_TIME_WATCHED", "type": "FLOAT" }, { "name": "AVG_COMPLETION_RATE", "type": "FLOAT" }, { "name": "AVG_VIDEO_DURATION", "type": "FLOAT" }, { "name": "AVG_VIDEO_VIEWS", "type": "FLOAT" }, { "name": "AVG_ENTERTAINMENT_SCORE", "type": "FLOAT" }, { "name": "COMMENT_SENTIMENT_POSITIVE_RATE", "type": "FLOAT" }, { "name": "COMMENT_SENTIMENT_NEUTRAL_RATE", "type": "FLOAT" }, { "name": "COMMENT_SENTIMENT_NEGATIVE_RATE", "type": "FLOAT" } ] } } ``` # Connect BigQuery to Dash Social Source: https://developer.dashsocial.com/guides/integration/connect-bigquery-to-dash-social/index Set up Dash Social's BigQuery integration to export daily social metrics into your data warehouse. If organic metrics (e.g. AVG\_REACH, VIDEO\_VIEWS) appear as NULL in your Facebook table, this is likely because your Meta Ads account is not connected to Dash Social. See [Connecting Your Meta Ads Account to Dash Social](https://help.dashsocial.com/hc/en-us/articles/4408951687181-Connecting-Your-Meta-Ads-Account-to-Dash-Social) for more details. # Overview This guide shows you how to connect Dash Social to BigQuery so your social metrics are stored and updated in your own data warehouse. From there, you can query the data directly or connect tools like Looker or Power BI to build custom dashboards and reports without needing to move the data elsewhere. The integration runs automatically every day at **6 AM ET**, ensuring your data stays fresh and ready for reporting. *** # Use Case Examples * Monitor Instagram reach in a custom Looker dashboard * Feed Facebook ad performance data into a weekly Power BI report * Run SQL queries on TikTok video engagement trends *** # Before You Start Make sure you have: * Access to a Google Cloud project with BigQuery enabled * Permissions to create datasets and tables * Your Dash Social account ready to connect ## Supported Channels Dash Social currently supports BigQuery exports for the following platforms: * **Instagram Feed** * **Instagram Stories** * **TikTok** * **Facebook** Each channel requires a dedicated table with the correct schema. You can choose which channels to enable based on your reporting needs. *** # Implementation ## Set Up BigQuery ### Step 1: Create a Project and Dataset 1. Use your existing GCP project or create a new one (e.g. `marketing-data-prod`). 2. Inside BigQuery, create a new dataset (e.g. `social_analytics`). * We recommend creating a dedicated dataset for Dash Social to keep things clean and organized. ### Step 2: Create Tables for Each Channel You'll need a separate table for each social channel you want to track (e.g. Facebook, TikTok, Instagram). 1. In your dataset, create one **empty table** per channel. 2. Find all schema here: * [Instagram Feed Schema](/guides/integration/connect-bigquery-to-dash-social/instagram-feed-schema) * [Instagram Stories Schema](/guides/integration/connect-bigquery-to-dash-social/instagram-stories-schema) * [TikTok Schema](/guides/integration/connect-bigquery-to-dash-social/bigquery-tiktok-schema) * [Facebook Schema](/guides/integration/connect-bigquery-to-dash-social/bigquery-facebook-schema) 3. Define the schema for the table: * Manually via the BigQuery console, or * Using the [BigQuery API Explorer](https://cloud.google.com/bigquery/docs/reference/rest/v2/tables/insert) * Use the BigQuery CLI If you're comfortable with the command line, you can use the BigQuery CLI to create tables quickly from a local JSON schema file. #### Step 1: Save your schema file in Cloud Shell In your Cloud Shell terminal, run: ``` nano ~/facebook_metrics.json ``` Paste your schema in the following format: ```json theme={null} [ { "name": "DATA_SYNC_TIME", "type": "DATETIME" }, { "name": "REPORTING_PERIOD_START_DATE", "type": "DATE" }, { "name": "REPORTING_PERIOD_END_DATE", "type": "DATE" }, { "name": "REPORTING_PERIOD_IN_DAYS", "type": "INTEGER" }, { "name": "IMPRESSIONS", "type": "FLOAT" }, { "name": "CLICKS", "type": "FLOAT" }, { "name": "ENGAGEMENTS", "type": "FLOAT" } ] ``` You can find all Schema here: * [Instagram Feed Schema](/guides/integration/connect-bigquery-to-dash-social/instagram-feed-schema) * [Instagram Stories Schema](/guides/integration/connect-bigquery-to-dash-social/instagram-stories-schema) * [TikTok Schema](/guides/integration/connect-bigquery-to-dash-social/bigquery-tiktok-schema) * [Facebook Schema](/guides/integration/connect-bigquery-to-dash-social/bigquery-facebook-schema) Press Control + O to save, then Enter, then Control + X to exit. #### Step 2: Run the CLI command Use this command to create the table in BigQuery: ``` bq mk --table \ marketing-data-prod:social_analytics.facebook_metrics \ ~/facebook_metrics.json ``` Make sure to replace: * projectID: e.g. marketing-data-prod * datasetID: e.g. social\_analytics * tableID: e.g. facebook\_metrics This method is useful if you're creating multiple tables or scripting the setup process. Repeat this step for each channel you want to integrate. ## Connect to Dash Social ### Step 3: Link BigQuery in Dash Social 1. In Dash Social, go to **Settings > Integrations**. 2. Click **BigQuery**. 3. For each workflow (channel), enter the correct values: * `projectID`: e.g. `marketing-data-prod` * `datasetID`: e.g. `social_analytics` * `tableID`: e.g. `tiktok_metrics` **Don't paste the full table path into each field. Instead, break it into three parts.** If your full BigQuery table path is: ``` marketing-data-prod.social_analytics.tiktok_metrics ``` You should enter: | Field | Correct Input | | ----------- | --------------------- | | `projectID` | `marketing-data-prod` | | `datasetID` | `social_analytics` | | `tableID` | `tiktok_metrics` | Do **not** enter `marketing-data-prod.social_analytics.tiktok_metrics` into any of the fields. 4. Set the **Reporting Period in Days** (e.g. `7` for the last 7 days). 5. Click **Save**. Dash Social will now begin writing daily updates into your specified tables. *** # Final Outcome Once connected, your BigQuery tables will be automatically populated with fresh social metrics daily. This makes it easy to build dashboards, run queries, and feed marketing data into analytics pipelines. # BigQuery: Instagram Feed Owned Metrics Schema Source: https://developer.dashsocial.com/guides/integration/connect-bigquery-to-dash-social/instagram-feed-schema This schema includes all the available metrics for Instagram on Dash Social's Dashboard solution. Note that it excludes stories. ```json theme={null} { "schema": { "fields": [ { "name": "DATA_SYNC_TIME", "type": "DATETIME" }, { "name": "REPORTING_PERIOD_START_DATE", "type": "DATE" }, { "name": "REPORTING_PERIOD_END_DATE", "type": "DATE" }, { "name": "REPORTING_PERIOD_IN_DAYS", "type": "INTEGER" }, { "name": "AVG_EFFECTIVENESS", "type": "FLOAT" }, { "name": "AVG_EFFECTIVENESS_VIDEO", "type": "FLOAT" }, { "name": "AVG_EFFECTIVENESS_REEL", "type": "FLOAT" }, { "name": "AVG_EFFECTIVENESS_PHOTO", "type": "FLOAT" }, { "name": "AVG_EFFECTIVENESS_CAROUSEL", "type": "FLOAT" }, { "name": "AVG_EFFECTIVENESS_VIDEO_REEL", "type": "FLOAT" }, { "name": "AVG_EFFECTIVENESS_PHOTO_CAROUSEL", "type": "FLOAT" }, { "name": "AVG_ENGAGEMENT_RATE", "type": "FLOAT" }, { "name": "AVG_ENGAGEMENT_RATE_VIDEO", "type": "FLOAT" }, { "name": "AVG_ENGAGEMENT_RATE_REEL", "type": "FLOAT" }, { "name": "AVG_ENGAGEMENT_RATE_PHOTO", "type": "FLOAT" }, { "name": "AVG_ENGAGEMENT_RATE_CAROUSEL", "type": "FLOAT" }, { "name": "AVG_ENGAGEMENT_RATE_VIDEO_REEL", "type": "FLOAT" }, { "name": "AVG_ENGAGEMENT_RATE_PHOTO_CAROUSEL", "type": "FLOAT" }, { "name": "AVG_REACH", "type": "FLOAT" }, { "name": "FOLLOWER_GROWTH_RATE", "type": "FLOAT" }, { "name": "LIKESHOP_CLICKS", "type": "FLOAT" }, { "name": "NET_NEW_FOLLOWERS", "type": "FLOAT" }, { "name": "NUMBER_OF_POSTS", "type": "FLOAT" }, { "name": "NUMBER_OF_POSTS_VIDEO", "type": "FLOAT" }, { "name": "NUMBER_OF_POSTS_REEL", "type": "FLOAT" }, { "name": "NUMBER_OF_POSTS_CAROUSEL", "type": "FLOAT" }, { "name": "NUMBER_OF_POSTS_VIDEO_REEL", "type": "FLOAT" }, { "name": "NUMBER_OF_POSTS_PHOTO_CAROUSEL", "type": "FLOAT" }, { "name": "ORGANIC_COMMENTS", "type": "FLOAT" }, { "name": "IMPRESSIONS", "type": "FLOAT" }, { "name": "ORGANIC_LIKES", "type": "FLOAT" }, { "name": "ORGANIC_VIDEO_VIEWS", "type": "FLOAT" }, { "name": "ORGANIC_VIDEO_VIEWS_REEL", "type": "FLOAT" }, { "name": "SUM_TOTAL_ENGAGEMENTS", "type": "FLOAT" }, { "name": "PAID_COMMENTS", "type": "FLOAT" }, { "name": "PAID_IMPRESSIONS", "type": "FLOAT" }, { "name": "PAID_LIKES", "type": "FLOAT" }, { "name": "PAID_VIDEO_VIEWS", "type": "FLOAT" }, { "name": "PAID_VIDEO_VIEWS_VIDEO", "type": "FLOAT" }, { "name": "PAID_VIDEO_VIEWS_REEL", "type": "FLOAT" }, { "name": "PAID_TOTAL_ENGAGEMENTS", "type": "FLOAT" }, { "name": "PROFILE_VIEWS", "type": "FLOAT" }, { "name": "SAVES", "type": "FLOAT" }, { "name": "SHARES", "type": "FLOAT" }, { "name": "SHARES_REEL", "type": "FLOAT" }, { "name": "TEXT_MESSAGE_CLICKS", "type": "FLOAT" }, { "name": "TOTAL_COMMENTS", "type": "FLOAT" }, { "name": "TOTAL_ENGAGEMENTS", "type": "FLOAT" }, { "name": "TOTAL_FOLLOWERS", "type": "FLOAT" }, { "name": "TOTAL_IMPRESSIONS", "type": "FLOAT" }, { "name": "TOTAL_LIKES", "type": "FLOAT" }, { "name": "TOTAL_VIDEO_VIEWS", "type": "FLOAT" }, { "name": "TOTAL_VIDEO_VIEWS_VIDEO", "type": "FLOAT" }, { "name": "TOTAL_VIDEO_VIEWS_REEL", "type": "FLOAT" }, { "name": "WEBSITE_CLICKS", "type": "FLOAT" }, { "name": "EMAIL_CONTACT_CLICKS", "type": "FLOAT" }, { "name": "FOLLOWERS_LOST", "type": "FLOAT" }, { "name": "GET_DIRECTION_CLICKS", "type": "FLOAT" }, { "name": "NUMBER_OF_POSTS_PHOTO", "type": "FLOAT" }, { "name": "ORGANIC_VIDEO_VIEWS_VIDEO", "type": "FLOAT" }, { "name": "AVG_ENTERTAINMENT_SCORE_REEL", "type": "FLOAT" }, { "name": "COMMENT_SENTIMENT_POSITIVE_RATE", "type": "FLOAT" }, { "name": "COMMENT_SENTIMENT_NEUTRAL_RATE", "type": "FLOAT" }, { "name": "COMMENT_SENTIMENT_NEGATIVE_RATE", "type": "FLOAT" } ] } } ``` # BigQuery: Instagram Stories Owned Metrics Schema Source: https://developer.dashsocial.com/guides/integration/connect-bigquery-to-dash-social/instagram-stories-schema ```json theme={null} { "schema": { "fields": [ { "name": "DATA_SYNC_TIME", "type": "DATETIME" }, { "name": "REPORTING_PERIOD_START_DATE", "type": "DATE" }, { "name": "REPORTING_PERIOD_END_DATE", "type": "DATE" }, { "name": "REPORTING_PERIOD_IN_DAYS", "type": "INTEGER" }, { "name": "AVG_EXIT_RATE", "type": "FLOAT" }, { "name": "AVG_COMPLETION_RATE", "type": "FLOAT" }, { "name": "AVG_REACH", "type": "FLOAT" }, { "name": "EXITS", "type": "FLOAT" }, { "name": "IMPRESSIONS", "type": "FLOAT" }, { "name": "REPLIES", "type": "FLOAT" }, { "name": "TAPS_FORWARD", "type": "FLOAT" }, { "name": "TAPS_BACK", "type": "FLOAT" }, { "name": "NUMBER_OF_POSTS", "type": "FLOAT" }, { "name": "SWIPE_UPS", "type": "FLOAT" } ] } } ``` # Integrating with Salesforce Source: https://developer.dashsocial.com/guides/integration/salesforce-installation-guide How to install and configure the Dash Social x Salesforce integration and start escalating messages. Bridge the gap between your social, moderation, and customer support teams with Dash Social's Salesforce Service Cloud integration. Once set up, you can escalate Community messages into cases for your customer support team to handle directly from within Salesforce. The best part: conversations stay in sync across Dash and Salesforce, so everyone's aligned. In this article, we'll walk you through how to install and configure the Dash Social x Salesforce integration and start escalating messages both manually and through automations. This integration is available in Dash Social's Advance plan and above. Salesforce API access is also limited to the Enterprise, Unlimited, and Performance editions of Salesforce, as well as Professional Editions with the paid API add-on. See Salesforce documentation for more information. # Getting Started Before you begin, ensure you have: * Salesforce admin access to install managed packages and configure components. * Dash Social admin access to connect your Salesforce organization. *** # Installation Steps This section contains the following steps: 1. Installing the Managed Package from Dash Social 2. Configuring App Manager Permissions in Salesforce 3. Embedding Dash Social to Your Salesforce Case Page Layout 4. Connecting Salesforce to Dash Social 5. Setting Up Field Mapping 6. Testing the Integration *** ## Step 1: Install the Managed Package from Dash Social The first thing you'll need to do is install the managed package available from within Dash Social. You must have Salesforce admin access to install managed packages and configure components. 1. In Dash Social, go to [Settings](https://app.dashsocial.com/settings/integrations) → [Integrations](https://app.dashsocial.com/settings/integrations). 2. Locate Salesforce in the integrations list and click Connect Salesforce. ![](https://files.readme.io/67f52f2194b31a8b29d2e05b1ef7348aae02e7763d04adccbc58d32c19319777-image.png) 3. Click **Install Salesforce App**. This will open a new window to Salesforce. 4. On the Salesforce installation screen, select **Install for Admins Only** (recommended for initial setup). 5. Check the acknowledgment box regarding Non-Salesforce Applications and click **Install**. ![](https://files.readme.io/beba45dfdc1767cfad47d0ec944cda6019706fa8d5629041031a10fe1c50b805-image.png) 6. Wait for the installation to finish. This may take a few minutes. 7. Once installed, you'll see "Dash Social - Community" in your list of Installed Packages in Salesforce. ![](https://files.readme.io/41e9921dd151618e93466828d14d709ae6aabd314188aab3708396f49033fec1-image.png) *** ## Step 2: Configure App Manager Permissions By default, permissions are set to "All users may self-authorize", which requires each user to individually authorize themselves when they first access the Dash Social component in Salesforce. For a more streamlined experience, we recommend changing this to "Admin approved users are pre-authorized", which pre-authorizes specific users/profiles to skip individual authorization. Here's how to configure permissions in App Manager: 1. In Salesforce, navigate to **Setup** → **App Manager**. 2. Locate the "Dash Social - Community" connected app, click the dropdown arrow, and select **Manage**. 3. Under **OAuth Policies**, next to **Permitted Users**, switch from "All users may self-authorize" and select "Admin approved users are pre-authorized". Click **Save** to apply this change. ![](https://files.readme.io/16697e44cae554da6407f27b1d7a9aa7f81af1cab6b48a47bb51c53e9b2b822a-image.png) 4. Next, click **Manage Profiles** or **Manage Permission Sets**. 5. Select any profiles/permission sets that should have access and click **Save**. *** ## Step 3: Embedding Dash Social to Case Pages Next, you will need to add the Dash Social component to your case page layout in Salesforce so you can respond to Community messages directly within Salesforce. Both processes are outlined below: ### Using Lightning Experience To embed Dash Social to case pages using Salesforce's Lightning Experience, follow the steps below: 1. Navigate to **Setup** → **Object Manager**. 2. Search for and select **Case**. You can also access it directly on the Cases page. ![](https://files.readme.io/c8a0008483b093f62a43c29545e017535d1a96cbacbfc0ea1d702f21e3651ee6-image.png) 3. Click **Lightning Record Pages**. 4. Select your Case record page (or create a new one). 5. Click **Edit** to open the Lightning App Builder. 6. In the **Components** panel, click on the **Tabs** component in your page layout to view the tab configuration. ![](https://files.readme.io/66391b00b4b34a42371e2dfb999bf6bda8c43aa4e7a3e83badea16c7e7c1e0ab-image.png) 7. Click **Add Tab** to create a new tab. Then configure the new tab as follows: * Tab Label: Enter "Dash Social" (or your preferred name). * Custom Label: Enter "Dash Social" in the Custom Label field. ![](https://files.readme.io/453baec7b6425dd66cf2f71ff31d3433cd121054888e08b4dbf4b1925d047785-image.png) 8. With the new tab selected, click **Components** in the left sidebar. 9. Scroll down to the "Visualforce" section. 10. Drag the "Dash Social - Community" component into the tab. 11. Set the "Height" component to 1000 pixels or adjust as needed. 12. Click **Save**. 13. Click **Activate** (if not already active) and assign to the appropriate app, record type, and profiles as needed. At this stage, visiting the Dash Social tab within a case won't show any data yet. You still need to finish the connection back in Dash Social and create a case. ![](https://files.readme.io/86fe1d7668e80f551c0cf639827b25b61c936773b1c0d5f8016b987ba53b0b0d-image.png) ### Using Classic Experience To embed Dash Social to case pages using Salesforce's Classic Experience, follow the steps below: 1. Navigate to **Setup** → **Object Manager** → **Case**. 2. Click **Page Layouts**. 3. Select your Case page layout. 4. In the page layout editor: * Click **Visualforce Pages** in the left sidebar. * Drag "Dash Social - Community" onto the page. * Set the height to 1000 pixels. 5. Click **Save**. At this stage, visiting the Dash Social tab within a case won't show any data yet. You still need to finish the connection back in Dash Social and create a case. *** ## Step 4: Connect Salesforce to Dash Social Now that you've finished installing Dash Social within Salesforce, it's time to finish the integration process by granting Dash Social permissions to create and update Salesforce cases. You must have Salesforce admin access to complete this authorization. 1. Back in Dash Social, go to [**Settings** → **Integrations** → **Salesforce**](https://app.dashsocial.com/settings/integrations). 2. Click **Connect Salesforce**. You'll then be redirected to a Salesforce authorization page. 3. Ensure the following permissions are enabled: * "Access the identity URL service" * "Manage user data via APIs" * "Perform requests at any time" 4. **Click** Allow to authorize the connection. You'll then be redirected back to Dash Social. ![](https://files.readme.io/71c7f01d7860a7a6ffcfb687d36bc8e87dd50a23eb1f1f183cca960b4ac8ee6c-image.png) 5. Confirm that Salesforce shows as "Connected". *** ## Step 5: Setup Field Mapping Now that Dash Social and Salesforce are connected, you will need to map your message fields in Community to Salesforce case fields. This ensures any messages escalated from Dash are tied to any required case fields when they appear within Salesforce. To set up field mapping: 1. In Community, click the three dots in the upper-right corner. 2. From the dropdown, select **Manage Integrations** → **Salesforce**. 3. In the window that appears, start by selecting a **Salesforce Record Type**. You can also select "None (Use Default)". The chosen Record Type controls which fields from Salesforce are available and required. If you're connecting multiple brands from Dash Social to the same Salesforce organization, we recommend using a separate record type per brand or mapping a custom field for each brand as an identifier. 4. Select a Salesforce field from the dropdown, then select a Dash Social message field to map it to. For example: * Map "Status > Escalated" from Salesforce to "Message State > Response Recommended" from Dash. * Map "Priority > High" from Salesforce to "Comment Sentiment> Negative" from Dash. * Map "Name" from Salesforce to "User Social Handle" from Dash. 5. Click **Add Mapping Field +** to map additional fields, doing so as many times as needed. 6. Once you're happy with your selection, click **Save** to apply your field mappings. Any new messages escalated from Dash Social to Salesforce will include these fields. Unmapped fields will be left empty. You can modify field mappings at any time after initial setup! Simply repeat the steps in this section. ![](https://files.readme.io/75031b35fa84c2d7acca21e8593df9df7a8dcfa5b4304837e3320ad284d101b0-image.png) *** ## Step 6: Test the Integration You're almost finished! As a final step, we recommend creating a test case to ensure your integration and mapped fields are working how you wish. To create a test case: 1. Go to your [Community Inbox](https://app.dashsocial.com/community) and find a message you want to escalate. 2. Click on the 3-dots next to the message. Then click **Create Salesforce Case** from the dropdown. 3. Head over to Salesforce and navigate to the **Cases** tab. 4. Open the case record you just created in Dash. 5. Verify your field mappings are working as desired. Back in Dash Social, the Salesforce case number will be displayed next to the message for easy reference! 6. Click the **Dash Social** tab to manage the message. 7. Confirm that the conversation loads in the Dash Social component. 8. Test replying to the customer directly from Salesforce. 9. Finally, head back to Dash Social to verify that case updates in Salesforce sync back to Dash. If you configured "Admin approved users are pre-authorized" in Step 2, the first time a user accesses the Dash Social tab, they may see an authorization popup. All they need to do is click Allow Access to complete OAuth flow! After authorization, the Dash Social component will load. *** # Creating Cases Now that you've successfully integrated with Salesforce, you can escalate any messages to Salesforce from your Community Inbox in Dash. To create a case, simply open the message that you would like to escalate to Salesforce, click on the 3-dots next to the message, then select Create Salesforce Case from the dropdown. Just like that, your message will automatically appear within your Salesforce cases along with the field mappings you've established during setup. Back in Dash Social, the Salesforce case number will be displayed next to the message for easy reference! ![](https://files.readme.io/d6fb82a75045cd6e8ebfc3c1ade55ff7e4fa95e660a29bb69f3fb630d5a9340d-image.png) ### Automating Case Creation Speed up the process of handling messages and escalating them as cases with the help of inbox automation rules in Community. Using these rules, you can automate various message actions, including Salesforce case creation, based on set criteria such as keywords, sentiment and more. To learn more, read our article on [Automating Your Community Inbox](https://help.dashsocial.com/hc/en-us/articles/28866944080141). Automation rules are optional. You can always create cases manually from Dash Social, regardless of your rule configuration. You can create multiple rules for different scenarios and enable/disable them as needed. ![](https://files.readme.io/d22ea4d441bcde143d32bcbb6f00f24816e2dddd12895182d62802253f5e5b8b-image.png) *** # Frequently Asked Questions Yes! You can modify field mappings any time after initial setup. When integrating with Salesforce, Dash Social will request permission to: * "Access the identity URL service" to verify your Salesforce organization * "Manage user data via APIs" to create and update cases with social media data * "Perform requests at any time" which is required to sync data between Dash Social and Salesforce. Once you've finished setting up the integration, Dash Social will have access to the following information from Salesforce for the purpose of creating and updating cases: * Case Fields: To create and populate cases with social media messages. * Account Information: To link cases to the correct customer accounts. * User Details: To assign cases to appropriate team members. * Field Metadata: To show you available mapping options during setup. # Dash Social MCP Server Guide Source: https://developer.dashsocial.com/guides/mcp-server/mcp-guide Installing the Dash Social MCP, how you can use it, and tips for getting reliable results. Bring your brand's intelligence directly into the AI tools you're already working in, without stitching together exports or toggling between tabs. The Dash Social MCP allows you to connect your brand’s performance data, competitive benchmarks, community insights, and more into your chosen AI platform like ChatGPT or Claude, so you can build custom workflows and access insights. This guide covers how to install the MCP and how you can use it as the default social data layer inside the AI platforms your team is using. *** ## What is MCP? Model Context Protocol (MCP) is an open standard that allows AI applications like ChatGPT or Claude to securely access external data sources and tools. The Dash Social MCP server provides AI assistants with direct access to your brand’s metrics, posts, and community data. When you connect the Dash Social MCP, your AI assistant can pull your Dash data based on natural-language questions about social performance. You can also use it to build custom workflows across other tools you’ve connected to your AI assistant, such as Google Drive or Slack. *** ## How You Can Use It Here are a few ways teams are already using the Dash Social MCP to elevate their social media management: * **Performance Reporting:** Ask your AI assistant to pull the latest data from Dash and populate your team's reporting template, then share it via Slack once it's approved. No more manual data pulls. * **Post Performance and Creative Intelligence:** Dig into post-level data across channels, including owned and UGC content. Analyze performance by post type, format, and theme without building manual reports. * **Community Insights:** Surface what your audience is saying. The MCP gives you access to comment and DM data, top keywords, sentiment breakdowns, and community overview metrics — all read-only, so nothing gets changed without your intent. * **Competitive Research:** Ask your AI assistant to research your brand's positioning and public perception with Dash's competitive benchmarks and industry data built right in. * **Content Scheduling:** Identify gaps in your calendar, pull assets from your content library or upload new ones, draft them into posts across brands and channels, and schedule directly into Dash at your best times to post. These are just a few ideas to get you started, but the only limit is your imagination! *** ## Before You Start **Check with your IT team first.** Setup is often handled by an admin and many organizations restrict which AI clients and connectors employees can use. Confirm which of the clients below are approved at your company before you start. In order to connect the Dash Social MCP, make sure you have: * A Dash Social account with access to the brands you want to use. * An MCP client that supports remote MCP servers, such as Claude or ChatGPT. Some AI platforms may limit MCP integrations to specific plans. *** ## Connecting the MCP The Dash Social MCP is a remote server, so there is nothing to "install" locally. All you need to do is connect your AI client to the server URL and authenticate with your Dash account! If your admin has already set up the Dash Social connector, you can skip the setup steps below. Just find "Dash Social" in your connectors/apps list and add it to your account. The Dash Social MCP is available with the Premium Analytics add-on and mirrors your existing Dash Social permissions. Your AI assistant can only access the brands and features you already have in Dash Social. Server URL: ```text theme={null} https://mcp.dashsocial.com/mcp ``` Open **Customize**, then **Connectors**. Claude Connectors menu Click the **+** button → **Custom connector**. Add custom connector button Name it "Dash Social MCP", paste the server URL above and click **Connect**. Add Custom Connector 1 Complete the authentication prompt to link your Dash Social account. Connect to MCP server The Dash Social tools are now available in your conversations. "Pro" models (o1-pro, o3-pro) are not supported with Custom Apps. Use standard models like GPT-4o instead. Open **Settings** → **Security and log in** → **Developer mode**. Toggle Developer mode. Chatgpt Menu Chatgpt Developer Mode Return to the main page and open **Plugins**. Click the **+** sign to create a new plugin. Chatgpt Plugins Name it "Dash Social MCP", paste the server URL above, and click **Create**. Chatgpt Create App Page Complete the authentication prompt to link your Dash Social account. Chatgpt Add Dash To Chatgpt Connect to MCP server The Dash Social tools are now available in your conversations. Microsoft 365 Copilot **Premium** is required. The standard Copilot subscription does not support MCP connections. Microsoft does not support dynamic client registration, so Dash Social provisions a **client ID** and **client secret** for each customer. Contact your account representative to get yours before starting. ### Part 1: IT admin setup Open the **Teams Developer Portal** and go to **Tools** → **OAuth client registration**. Teams Developer Portal OAuth client registration Click **New registration** and give it a name such as "Dash Social MCP". Enter the Dash Social MCP server URL, then set availability to **My organization only**. Server URL and organization scope Enter the client ID and client secret provided by Dash Social. Client ID and secret fields Enter the following endpoints. The refresh endpoint is the same as the token endpoint. | Field | Value | | ---------------------- | --------------------------------------------- | | Authorization endpoint | `https://auth.dashsocial.com/oauth/authorize` | | Token endpoint | `https://auth.dashsocial.com/oauth/token` | | Refresh endpoint | `https://auth.dashsocial.com/oauth/token` | Add `mcp:read` and `mcp:write` as the scopes. Leave **Client password authentication method** set to its default, **Request body parameters**. Authorization, token, and refresh endpoints Save the registration. Copy the registration client ID it generates. Registration client ID Go to **Copilot administration** → **Connectors** → **Gallery** → **Create a new connector**, then choose **Connect to MCP server**. Add new connector in the Copilot gallery Choose Connect to MCP server Name it "Dash Social MCP", enter the server URL again, and set the authentication method to **OAuth 2**. For **Reference ID**, paste the registration client ID you copied earlier. Connector configuration with reference ID Click **Authorize** and sign in to Dash Social when prompted, then click **Create** to finish. The connection is now created and available to your organization. Authorize and connect to Dash Social ### Part 2: User setup In Microsoft 365 Copilot, open the settings pane and go to **Sources**. Microsoft 365 Copilot settings Search for "Dash", select the Dash Social MCP connector, and click **Connect**. In the confirmation dialog, click **Continue to Dash MCP**. Search and connect to Dash Social MCP Connect to Dash Social MCP Complete the authentication prompt to link your Dash Social account, then close the settings pane. Dash Social authentication prompt The Dash Social tools are now available in your conversations. Most clients that support MCP servers with OAuth will be able to connect to the Dash MCP. These are instructions to connect any tool. Look for an MCP, connectors, or integrations section in the client's settings, or an MCP config file if it is configured through JSON. Check your client's documentation for the exact location. Name it "Dash Social MCP" and paste the server URL above. For clients that use a config file, add: ```json theme={null} { "mcpServers": { "dash-social": { "url": "https://mcp.dashsocial.com/mcp" } } } ``` Complete the authentication prompt to link your Dash Social account. If you edited a config file, restart the client first. For clients that only support local servers, use a remote bridge such as `mcp-remote` pointed at the server URL. For clients that only support local servers, use a remote bridge such as `mcp-remote` pointed at the URL. *** ## Tips for Better Results Now that you’re connected, here’are a few tips to help you get faster, more accurate answers: * **Mention your brand by name.** If you have access to multiple brands, mention which one you're asking about. For example: "Show me engagement for Adore Collective last month." * **Specify your time frame.** Include dates or time periods in your questions. For example: "What was our Instagram reach in March?" or "Show me trends over the past 90 days." * **Set up your tracked competitors first.** You can only compare against competitors that are already tracked in your Dash Social account. If a competitor isn't showing up, check that they're added in Settings. ### Allow access to media Ask Claude to create a PowerPoint, Word doc, or PDF that includes thumbnails of your posts, or to upload new media into your Dash library. Both need permission for Claude to access Dash's image hosting. Here's how: Go to **Settings → Capabilities**. On Team or Enterprise plans, look for **Organization settings → Capabilities** instead. Toggle **Code execution and file creation** on, then toggle **Allow network egress** on. Under **Additional allowed domains**, enter `*.dashsocial.com` and click **Add**. Add Dash Social domain to allowlist On Team and Enterprise plans, only an organization owner can change these settings. If the option is greyed out, ask your admin to add `*.dashsocial.com` to the allowlist. *** ## Frequently Asked Questions **Q. Which AI tools does the Dash Social MCP work with?** A. The Dash Social MCP is built on an open standard, meaning it's compatible with any AI platform that supports MCP. Popular options include ChatGPT and Claude. **Q. What data can my AI assistant access through the Dash Social MCP?** A. Your AI assistant can only access the brands and features you already have permissions for in Dash. You can control which brands are accessible by contacting your Dash Social admin. **Q. My authentication expired. What should I do?** A. Go back to your AI assistant's connector settings and reconnect the Dash Social MCP. You'll need to complete the authentication prompt again to re-link your account. *** ## Troubleshooting **"You don't have MCP access for this brand"** MCP access needs to be enabled for each brand separately. During authentication, you'll choose which brands can be accessed by your AI assistant. The MCP only grants the permissions you already have in Dash, so your brand data stays in your control. Even if you can see the brand in Dash Social, you may not have MCP access yet. Please contact your account representative to enable it. **“Can't find the metric you're looking for”** Try asking for one metric at a time using the same terms you see in Dash Social. If you're still not getting results, rephrase your question or ask the AI what metrics are available. **If results are empty or you’re missing data** Check that your brand actually published content during the time period you asked about. Empty results usually mean there was no activity to report. **Media thumbnails won't embed in my PowerPoint, doc, or PDF** Claude needs permission to download images from Dash. Add `*.dashsocial.com` to your allowlist under **Settings → Capabilities → Allow network egress** (see [Allow access to media](#allow-access-to-media) above). On Team and Enterprise plans, an organization owner has to make this change. **I can't upload media to Dash from Claude** Claude needs permission to upload images to Dash. Add `*.dashsocial.com` to your allowlist under Settings → Capabilities → Allow network egress (see [Allow access to media](#allow-access-to-media)). On Team and Enterprise plans, an organization owner has to make this change. # Download dashboard as Excel Source: https://developer.dashsocial.com/guides/reporting/download-dashboard-as-excel Download Dash Social dashboard data as XLSX files using the API for automated reporting and offline analysis. This guide shows you how to download dashboard data as Excel files using the Dash Social API. You'll get the same data you see in the Dashboards UI exported in XLSX format for offline analysis, automated reporting, or sharing with stakeholders. **Same format as UI downloads:** The Excel file format matches what you get when downloading from the Dash Social UI. The API automates the process and gives you control over custom date ranges. For how to download dashboards from the UI, see this [Help Center article](https://help.dashsocial.com/hc/en-us/articles/4411712032397-Introduction-to-Dashboards#h_01JHRPX0AJZ821P2WNGQT5D8Q2). *** ## Use cases The Dash Social UI lets you schedule dashboard emails, but the API goes further. Generate Excel exports with any date range on demand. This makes it ideal for automating reporting workflows and ingesting dashboard data directly into your data pipeline, eliminating manual downloads. Generate reports with dynamic ranges like "last Saturday to Sunday" that scheduled emails can't handle. Pull dashboard data programmatically for executive reports, pipelines, or offline analysis. No manual exports required. *** ## Before you start Make sure you have: * **Dashboard ID** - The unique identifier for the dashboard you want to download * **API Key** - Your authentication token from Dash Social If you need help getting your API key, check out our [API Quickstart](https://developer.dashsocial.com/guides/get-started/quickstart). **Finding your dashboard ID:** There's currently a limitation with the API. You cannot retrieve dashboard IDs programmatically. As a workaround, open the dashboard you want to download in the Dash Social app and look at the URL in your browser. The dashboard ID is the number immediately after `/dashboards/`. Examples: * `https://app.dashsocial.com/dashboards/33710/another-test-dashboard` → Dashboard ID is `33710` * `https://app.dashsocial.com/dashboards/62443` → Dashboard ID is `62443` *** ## Implementation ### Step 1: Generate the Excel export Send a GET request to generate the Excel file. The API creates a downloadable export with your specified date range and time breakdown. **Generation time:** This request may take a few seconds or longer depending on dashboard complexity and data volume. The API needs time to compile all metrics, graphs, and content data into the Excel file. ```http theme={null} GET https://dashboard.dashsocial.com/dashboards/33710?start_date=2025-11-01&end_date=2025-11-30&context_start_date=2025-11-01&context_end_date=2025-11-30&time_scale=DAILY&direct_download=true ``` #### Key query parameters * `start_date` / `end_date`: Your reporting date range. This determines which posts and activity are included. You can set any custom date range, including dynamic ranges like "last Saturday to this Sunday" that are not available with scheduled emails. * `context_start_date` / `context_end_date`: Your comparison period for trend analysis. Set these to match your reporting dates if you don't need comparison data. * `time_scale`: The granularity of time-series data. Options: * `DAILY`: Break down metrics by day * `WEEKLY`: Group metrics by week * `MONTHLY`: Group metrics by month * `direct_download=true`: Required. Always set this to `true` to generate an Excel file. **Dynamic date ranges:** Set date ranges programmatically in your code to create custom reporting periods. For example, calculate "last Saturday to this Sunday" dynamically and pass those dates to the API. **Date format:** Use `YYYY-MM-DD` format for date parameters (e.g., `2025-11-01`). You can optionally include time: `2025-08-10T02:00:00`. If you omit the time, it defaults to midnight UTC. #### Sample response The API returns a JSON object with a URL to download the Excel file: ```json theme={null} { "url": "https://dashsocial-static.s3.amazonaws.com/exports/xlsx/another-test-dashboard-2025-11-01-to-2025-11-30-1768485589.0119486-5db9a8cd5220872fac439f904d350bfd.xlsx" } ``` *** ### Step 2: Download the Excel file Use the URL from the response to download the Excel file. The file contains all dashboard data organized into sheets and tables. The Excel file includes: * **METRICS sheet**: Summary totals for the reporting period with comparison data * **GRAPHS sheet**: Time-series data broken down by your chosen `time_scale`. Charts are exported as data tables with numeric values (not visual graphs). * **Content sheets**: Post-level data organized by platform (Instagram, TikTok, Facebook, etc.) The file includes data from all brands configured in your dashboard. If you set multiple brands in the Dashboards UI, the Excel export will contain metrics and content from all of them combined. You can open this file in Excel, Google Sheets, or any spreadsheet application. **Programmatic downloads:** In your code, you'll need to: 1. Make the GET request to the dashboard endpoint 2. Parse the JSON response to extract the `url` field 3. Download the file from that URL 4. Save it to your local filesystem or send it where you need it Example in Python: ```python theme={null} import requests # Step 1: Request the dashboard export response = requests.get('https://dashboard.dashsocial.com/dashboards/33710?...') file_url = response.json()['url'] # Step 2: Download the Excel file file_response = requests.get(file_url) with open('dashboard.xlsx', 'wb') as f: f.write(file_response.content) ``` *** ## Next steps * [Export Dashboard Report Data via API →](/guides/export-dashboard-data) * [Fetch Metric Report Data via API →](/guides/metric-report) * [Visualize Time-Series Metrics with Graph Report →](/guides/graph-report) * [View the Full API Reference →](https://developers.dashsocial.com/reference/get_dashboards-id) # Community report overview Source: https://developer.dashsocial.com/guides/reporting/export-dashboard-report-data-via-api/community-report/overview Measure customer service team performance including response times and message volumes. Measures your team's performance responding to comments and DMs across social channels to track customer service metrics and response quality. **Available report types:** Pull Total Community Metrics Across Channels Track Community Metrics Over Time with Graph Report # Pull total community metrics across channels Source: https://developer.dashsocial.com/guides/reporting/export-dashboard-report-data-via-api/community-report/pull-total-community-metrics-across-channels Retrieve aggregated community management metrics like messages received and response times. Measure Community performance across social channels. Pull total metrics like messages received, response times, and response rates to quantify your team's customer service impact. *** ## Use cases Tracking Community team performance across platforms manually is time-consuming. Metric reports give you total performance numbers in seconds. Build a weekly report showing total messages received and response times across all social channels Track average response times and message volumes to ensure your team meets service level agreements Compare message volumes across Instagram, TikTok, and Facebook to allocate team resources effectively *** ## Before you start Make sure you have: * **API access token** with permissions to the relevant brand. * **Brand ID** for the account you want to query. See [API Quickstart](/guides/get-started/quickstart) for more details. **Test in the UI first:** Create a Dashboard in the Dash Social UI and configure your Community report there. This previews the metrics and validates your filters before writing code. **What metrics are included?** This report measures your team's performance in Community across connected social channels. Track metrics like messages received, response times, and engagement. *** **Supported platforms** This report supports these channels: * Instagram * TikTok * Facebook * YouTube * X **About metric reports** Metric reports return aggregated totals for your date range. Use metric reports when you need summed KPIs without time breakdowns. *** ## 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,146`)
`channels` Social platforms to include: * Instagram: `INSTAGRAM` * TikTok: `TIKTOK` * Facebook: `FACEBOOK` * YouTube: `YOUTUBE` * X: `TWITTER` Request multiple channels by separating with commas (e.g., `INSTAGRAM,TIKTOK,FACEBOOK`)
`metrics` Community metrics to return: * Messages Received: `MESSAGES_RECEIVED` - Total messages received * Reply Rate: `REPLY_RATE` - Percentage of messages replied to by your team * Response Time: `RESPONSE_TIME` - Average time to respond to messages Request multiple metrics by separating with commas (e.g., `MESSAGES_RECEIVED,REPLY_RATE,RESPONSE_TIME`)
`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. Use same dates if no comparison needed
`report_type` Set to `TOTAL_METRIC` for aggregated totals
*** ### Step 2: Make the API call Send a GET request using the parameters from Step 1. This example gets messages received for brand `144` on Instagram from May 1-7, with April 1-7 as the comparison period. ```http theme={null} GET 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=MESSAGES_RECEIVED &report_type=TOTAL_METRIC ``` **Date format matters:** Always use `YYYY-MM-DD` format for dates (e.g., `2025-05-01`). Other formats will cause errors. #### Sample response The response returns totals for each metric, organized by brand. The `value` field shows the metric total for your reporting period. The `context` field shows the comparison period total. The `context_change` field shows the percentage change. ```json theme={null} { "data": { "144": { "avatar": "https://cdn.dashsocial.com/avatars/2306810931.jpeg", "data_type": "BRAND", "name": "sunny.today", "user_has_access": true }, "metrics": { "MESSAGES_RECEIVED": { "ALL_CHANNELS": { "context": 3, "context_change": -0.3333333333333333, "value": 2 } } } }, "product_category": "COMMUNITY" } ``` **Understanding the response:** Metrics are organized by brand ID and aggregated across all channels. In this example, brand `144` ("sunny.today") received 2 messages during May 1-7, down from 3 during April 1-7. The `context_change` value of -0.333 indicates a 33.3% decrease compared to the previous period. Feed this data into your BI tool, dashboard, or analytics pipeline to track Community team performance. *** ## Next steps * [Visualize Time-Series Community Metrics with Graph Report →](/guides/community-graph-report) * [Track Individual Conversation Performance with Content Report →](/guides/community-content-report) * [Compare Community Performance Across Brands →](/guides/multi-brand-community-report) * [View the Full API Reference →](https://developers.dashsocial.com/reference/get_reports-data) # Track community metrics over time with graph report Source: https://developer.dashsocial.com/guides/reporting/export-dashboard-report-data-via-api/community-report/track-community-metrics-over-time-with-graph-report Visualize community team performance trends over time using time-series data. Track how your Community metrics change day by day across Instagram, TikTok, Facebook, YouTube, and X. This guide shows you how to pull time-series data using the Graph report. You'll get daily breakdowns ready to visualize trends and measure team performance over time. *** ## Use cases Measuring Community team performance at a single point in time doesn't show you the full picture. Graph reports give you daily metrics so you can spot patterns, track improvement, and measure the impact of process changes. Chart daily response times in Tableau to identify which days your team responds fastest and where bottlenecks occur Track message volumes over weeks to predict busy periods and adjust team scheduling Visualize response rate improvements after implementing new workflows or training *** ## Before you start Make sure you have: * **API access token** with permissions to the relevant brand. * **Brand ID** for the account you want to query. See [API Quickstart](/guides/get-started/quickstart) for more details. **Test in the UI first:** Create a Dashboard in the Dash Social UI and configure your Community graph report there. This lets you preview the time-series behavior and validate that your filters return the right data before writing any code. *** **Supported platforms** This report supports these channels: * Instagram * TikTok * Facebook * YouTube * X **About graph reports** Graph reports return daily values organized by date. Use graph reports when you want to chart trends or visualize changes over time. *** ## 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,146`)
`channels` Social platforms to include: * Instagram: `INSTAGRAM` * TikTok: `TIKTOK` * Facebook: `FACEBOOK` * YouTube: `YOUTUBE` * X: `TWITTER` Request multiple channels by separating with commas (e.g., `INSTAGRAM,TIKTOK,FACEBOOK`)
`metrics` Community metrics to track over time: * Messages Received: `MESSAGES_RECEIVED` - Total messages received * Reply Rate: `REPLY_RATE` - Percentage of messages replied to by your team * Response Time: `RESPONSE_TIME` - Average time to respond to messages Request multiple metrics by separating with commas (e.g., `MESSAGES_RECEIVED,REPLY_RATE,RESPONSE_TIME`)
`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. Use same dates if no comparison needed
`report_type` Set to `GRAPH` for time-series data
*** ### Step 2: Make the API call Send a GET request using the parameters from Step 1. This example gets daily messages received for brand `144` on Instagram from May 1-7, with April 1-7 as the comparison period. ```http theme={null} GET 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=MESSAGES_RECEIVED &report_type=GRAPH ``` **Date format matters:** Always use `YYYY-MM-DD` format for dates (e.g., `2025-05-01`). Other formats will cause errors. #### Sample response The response returns time-series data organized by date. Each metric has daily values for your reporting period. ```json theme={null} { "data": { "144": { "avatar": "https://cdn.dashsocial.com/avatars/2306810931.jpeg", "data_type": "BRAND", "metrics": { "MESSAGES_RECEIVED": { "ALL_CHANNELS": { "2025-05-02T00:00:00.000Z": 2 } } }, "name": "sunny.today", "user_has_access": true }, "metrics": { "MESSAGES_RECEIVED": { "ALL_CHANNELS": { "2025-05-02T00:00:00.000Z": 2 } } } }, "product_category": "COMMUNITY" } ``` **Understanding the response:** Metrics are organized by brand ID and grouped by channel. In this example: * Brand `144` ("sunny.today") received 2 messages on May 2, 2025 * The date is in ISO 8601 format with timezone (`2025-05-02T00:00:00.000Z`) * `ALL_CHANNELS` aggregates data if you requested multiple platforms Use this time-series data in BI tools like Power BI, Tableau, or Looker to create trend charts and spot patterns in your Community performance. **Want aggregated totals instead?** Use the [Community Metric report](/guides/community-metric-report) to get summed KPIs without time breakdowns. *** ## Next steps * [Get Aggregated Community Totals with Metric Report →](/guides/track-team-performance-with-metric-report) * [Track Individual Conversation Performance with Content Report →](/guides/community-content-report) * [Compare Community Performance Across Brands →](/guides/multi-brand-community-report) * [View the Full API Reference →](https://developers.dashsocial.com/reference/get_reports-data) # Compare competitor metrics across platforms Source: https://developer.dashsocial.com/guides/reporting/export-dashboard-report-data-via-api/competitor-report/compare-competitor-metrics-across-platforms Benchmark competitor performance metrics across Instagram, Facebook, YouTube, and X. Pull aggregated competitor metrics across platforms. Use the data to benchmark your performance and inform your content strategy. *** ## Use cases Tracking competitor performance manually across platforms wastes hours each week. Competitive metric reports give you cross-platform benchmarks instantly. Compare your posting cadence against competitor averages to optimize your content calendar Identify which platforms competitors post on most to guide your channel strategy Monitor competitor engagement over time to spot momentum shifts and emerging opportunities *** ## Before you start Prerequisites: * **API Key** - Your authentication token - Get your API key from the [API Quickstart](https://developer.dashsocial.com/guides/get-started/quickstart). * **Brand ID** - Your brand's unique ID * **Tracked Competitors** - Competitors added in Dash Social Supported platforms: * Instagram * Facebook * YouTube * X **Add competitors first:** Report on competitors tracked in Dash Social only. Add competitors in **Dash Social → Settings → Competitor Management** before using this API. ### Test in the dashboard first Preview competitive metrics in the Dash Social Dashboard to understand the data structure before pulling via API. *** ## Implementation ### Step 1: Get competitor account IDs Get source account IDs for your tracked competitors. Each competitor has a unique ID per platform. Send a POST request: ```http theme={null} POST https://library-backend.dashsocial.com/competitors/search body = { "source": "INSTAGRAM" } ``` #### Key query parameters * `source`: Platform to search: * Instagram: `INSTAGRAM` * Facebook: `FACEBOOK` * YouTube: `YOUTUBE` * Twitter (X): `TWITTER` Sample response: ```json theme={null} [ { "avatar_url": "https://cdn.dashsocial.com/avatars/2306810931.jpeg", "brand_details": [ { "brand_id": 144, "created_at": "2019-10-22T21:02:14+00:00" } ], "handle": "sunny.today", "source": "INSTAGRAM", "source_account_id": "2306810931" }, { "avatar_url": "https://cdn.dashsocial.com/avatars/230344968.jpeg", "brand_details": [ { "brand_id": 144, "created_at": "2020-03-15T10:22:33+00:00" } ], "handle": "fashionista_brand", "source": "INSTAGRAM", "source_account_id": "230344968" } ] ``` Collect each `source_account_id` value. Format as comma-separated: `2306810931,230344968`. ### Compare across platforms To compare multiple platforms, call `/competitors/search` separately for each platform. *** ### Step 2: Map your report parameters Map the available parameters before making the API call:
Parameter Description
`brand_ids` Your brand ID.
`channels` Competitive channel to report on: * Instagram: `INSTAGRAM_COMPETITIVE` * Facebook: `FACEBOOK_COMPETITIVE` * YouTube: `YOUTUBE_COMPETITIVE` * Twitter (X): `TWITTER_COMPETITIVE` Use the `_COMPETITIVE` suffix for competitor reports.
`metrics` Metric to rank posts by. See [Metrics](#metrics) section below for all options. Request multiple metrics by separating with commas (e.g., `TOTAL_ENGAGEMENTS,REACH,VIEWS`)
`competitor_source_account_ids` Comma-separated IDs from Step 1: `2306810931,230344968,232342925`
`start_date` / `end_date` Reporting period in `YYYY-MM-DD` format
`context_start_date` / `context_end_date` Comparison date range for period-over-period analysis. Use same dates as `start_date` / `end_date` if no comparison needed
`report_type` Set to `COMPETITIVE_MULTI_BRAND_METRIC` for this report
*** ### Step 3: Request the metric report Send a GET request using the parameters from Step 2. This example gets total posts published by competitors on Instagram during October 2025: ```http theme={null} GET https://dashboard.dashsocial.com/reports/data?brand_ids=144& channels=INSTAGRAM_COMPETITIVE& metrics=NUMBER_OF_POSTS& start_date=2025-10-01& end_date=2025-10-30& context_start_date=2025-09-01& context_end_date=2025-09-30& report_type=COMPETITIVE_MULTI_BRAND_METRIC& competitor_source_account_ids=2306810931,230344968,232342925 ``` This request uses: * Channel: `INSTAGRAM_COMPETITIVE` from Step 2 * Metric: `NUMBER_OF_POSTS` from Step 2 * Reporting period: October 2025 (`start_date` / `end_date`) * Comparison period: September 2025 (`context_start_date` / `context_end_date`) * Competitor IDs from Step 1 ### Compare multiple platforms Make separate requests for each channel: `INSTAGRAM_COMPETITIVE`, `FACEBOOK_COMPETITIVE`, etc. Combine results in your dashboard or analytics tool. Sample response: ```json theme={null} { "data": { "1005579026": { "avatar": "https://cdn.dashsocial.com/avatars/1005579026.jpeg", "data_type": "COMPETITOR", "metrics": { "NUMBER_OF_POSTS": { "INSTAGRAM_COMPETITIVE": { "context": 97, "context_change": -0.09278350515463918, "value": 88 } } }, "name": "competitor_alpha", "user_has_access": true }, "144": { "avatar": "https://cdn.dashsocial.com/avatars/2306810931.jpeg", "data_type": "BRAND", "metrics": { "NUMBER_OF_POSTS": { "INSTAGRAM_COMPETITIVE": { "context": 48, "context_change": -0.2708333333333333, "value": 35 } } }, "name": "your_brand", "user_has_access": true }, "230344968": { "avatar": "https://cdn.dashsocial.com/avatars/230344968.jpeg", "data_type": "COMPETITOR", "metrics": { "NUMBER_OF_POSTS": { "INSTAGRAM_COMPETITIVE": { "context": 25, "context_change": 0.04, "value": 26 } } }, "name": "competitor_beta", "user_has_access": true }, "2306810931": { "avatar": "https://cdn.dashsocial.com/avatars/2306810931.jpeg", "data_type": "COMPETITOR", "metrics": { "NUMBER_OF_POSTS": { "INSTAGRAM_COMPETITIVE": { "context": null, "context_change": null, "value": null } } }, "name": "competitor_gamma", "user_has_access": true }, "competitor_average": { "data_type": "COMPETITOR_AVERAGE", "metrics": { "NUMBER_OF_POSTS": { "INSTAGRAM_COMPETITIVE": { "context": 61.0, "context_change": -0.06557377049180328, "value": 57.0 } } }, "name": "Competitor Average", "user_has_access": true } }, "product_category": "COMPETITIVE" } ``` *** ### Step 4: Interpret the response The response includes data for each competitor plus a `competitor_average` summary. #### Response structure Each account includes: * `data_type`: `BRAND` (your brand), `COMPETITOR`, or `COMPETITOR_AVERAGE` * `name`: Account handle * `metrics`: Object containing requested metrics * `value`: Metric total for the reporting period * `context`: Metric total for the comparison period * `context_change`: Decimal representing percent change (e.g., `-0.09` = -9%, `0.04` = +4%) **Common errors:** * **Invalid channel name** - Use `INSTAGRAM_COMPETITIVE`, not `INSTAGRAM`. Competitive channels require the `_COMPETITIVE` suffix. * **Invalid source account ID** - Verify IDs match the `/competitors/search` response from Step 1. * **Missing context dates** - Include `context_start_date` and `context_end_date` for trend analysis. * **Null values in response** - Competitors may return `null` if no data exists for the period. *** ## Metrics | Metric Name | Description | Metric API Name | | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | | Avg. Engagement Rate - Public | The average percentage of people who engaged with your competitors' posts, based on their follower count | `AVG_ENGAGEMENT_RATE_PUBLIC` | | Avg. Estimated Reach | The average number of unique accounts that saw your posts published during the Reporting Period. The average estimated number of unique accounts that saw competitor's posts based on their number of followers during the Reporting Period. | `AVG_REACH` | | Followers - Growth Rate | The percentage of your competitors' followers increased by over the comparison period | `FOLLOWER_GROWTH_RATE` | | Followers - Net New | The net new number of people who followed your competitors' accounts | `NET_NEW_FOLLOWERS` | | Number of Posts | The number of posts you've published during the reporting period | `NUMBER_OF_POSTS` | | Comments | The number of comments your competitors' posts received | `ORGANIC_COMMENTS` | | Likes | The number of likes your competitors' posts received | `ORGANIC_LIKES` | | Followers | The total number of followers your competitors have on this channel | `TOTAL_FOLLOWERS` | | Metric Name | Description | Metric API Name | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | | Avg. Engagement Rate | The average engagement rate of your competitors' posts published during the Reporting Period. Engagement Rate = (Comments + Reactions + Shares) / Followers | `AVG_ENGAGEMENT_RATE_PUBLIC` | | Followers - Growth Rate | The percentage of your competitors' followers increased by over the comparison period | `FOLLOWER_GROWTH_RATE` | | Followers - Net New | The net new number of people who followed your competitors' accounts | `NET_NEW_FOLLOWERS` | | Number of Posts | The number of posts you've published during the reporting period | `NUMBER_OF_POSTS` | | Followers | The total number of followers your competitors have on this channel | `TOTAL_FOLLOWERS` | | Metric Name | Description | Metric API Name | | --------------------- | ------------------------------------------------------------------------------ | --------------------- | | Comments | The number of comments your competitors' posts received | `COMMENTS` | | Likes | The number of likes your competitors' posts received | `LIKES` | | Number of Posts | The number of posts your competitors published during the reporting period | `NUMBER_OF_POSTS` | | Subscribers - Net New | The net new number of people who have subscribed to your competitors' channels | `SUBSCRIBERS_NET_NEW` | | Subscribers | The total number of subscribers your competitors have on their channels | `SUBSCRIBERS_TOTAL` | | Video Views | The number of times the videos on your competitors' channels were viewed | `TOTAL_VIDEO_VIEWS` | | Metric Name | Description | Metric API Name | | ----------------------- | ---------------------------------------------------------------------------------- | ---------------------- | | Followers - Growth Rate | The percentage your competitors' followers increased by over the comparison period | `FOLLOWER_GROWTH_RATE` | | Likes | The number of likes your competitors' posts received | `LIKES` | | Followers - Net New | The net new number of people who followed your competitors' accounts | `NET_NEW_FOLLOWERS` | | Number of Posts | The number of posts your competitors published during the reporting period | `NUMBER_OF_POSTS` | | Quote Posts | The total number of times your competitors' posts were reposted with a quote | `QUOTE_POSTS` | | Replies | The total number of times your competitors' posts were replied to | `REPLIES` | | Reposts | The total number of times your competitors' posts were reposted | `REPOSTS` | | Engagements | The total number of engagements your competitors' posts received | `TOTAL_ENGAGEMENTS` | | Followers | The total number of followers your competitors have on this channel | `TOTAL_FOLLOWERS` | | Total Reposts | The total number of times your competitors' posts were reposted or quote posted | `TOTAL_RETWEETS` | | Video Views | The number of times your competitors' videos were viewed | `VIDEO_VIEWS` | ## Next steps With your competitive metrics, you can: * **Build benchmarking dashboards** - Compare your brand against competitor averages * **Track posting cadence trends** - Query monthly to spot competitor posting frequency changes * **Identify platform priorities** - Compare metrics across channels to see where competitors invest most * **Inform content strategy** - Use engagement metrics to understand what volume and frequency work for competitors # Get top competitor posts ranked by performance Source: https://developer.dashsocial.com/guides/reporting/export-dashboard-report-data-via-api/competitor-report/get-top-competitor-posts-ranked-by-performance Retrieve and rank top-performing competitor posts by engagement metrics across platforms. Pull top-performing posts from tracked competitors. Use the data to identify winning content formats and inform your creative strategy. *** ## Use cases Manually reviewing competitor content across platforms wastes hours each week. Competitive content reports surface top posts instantly. Surface top-performing competitor posts to inspire your creative team with proven formats and themes Benchmark your brand's best posts against what's resonating with competitor audiences Identify which post formats or topics drive results for competitors to inform your strategy *** ## Before you start Prerequisites: * **API Key** - Your authentication token - Get your API key from the [API Quickstart](https://developer.dashsocial.com/guides/get-started/quickstart). * **Brand ID** - Your brand's unique ID * **Tracked Competitors** - Competitors added in Dash Social Supported platforms: * Instagram * Facebook * YouTube * X **Add competitors first:** Report on competitors tracked in Dash Social only. Add competitors in **Dash Social → Settings → Competitor Management** before using this API. ### Test in the dashboard first Preview competitive content in the Dash Social Dashboard to understand the data structure before pulling via API. *** ## Implementation ### Step 1: Get competitor account IDs Get source account IDs for your tracked competitors. Each competitor has a unique ID per platform. Send a POST request: ```http theme={null} POST https://library-backend.dashsocial.com/competitors/search body = { "source": "FACEBOOK" } ``` #### Key query parameters * `source`: Platform to search: * Instagram: `INSTAGRAM` * Facebook: `FACEBOOK` * YouTube: `YOUTUBE` * Twitter (X): `TWITTER` Sample response: ```json theme={null} [ { "avatar_url": "https://cdn.dashsocial.com/avatars/2306810931.jpeg", "brand_details": [ { "brand_id": 144, "created_at": "2019-10-22T21:02:14+00:00" } ], "handle": "sunny.today", "source": "FACEBOOK", "source_account_id": "2306810931" }, { "avatar_url": "https://cdn.dashsocial.com/avatars/230344968.jpeg", "brand_details": [ { "brand_id": 144, "created_at": "2020-03-15T10:22:33+00:00" } ], "handle": "scaniagroup", "source": "FACEBOOK", "source_account_id": "230344968" } ] ``` Collect each `source_account_id` value. Format as comma-separated: `2306810931,230344968,232342925`. ### Track multiple platforms To analyze competitor content across Instagram and Facebook, call `/competitors/search` separately for each platform. *** ### Step 2: Map your report parameters Map the available parameters before making the API call:
Parameter Description
`brand_ids` Your brand ID.
`channels` Competitive channel to report on: * Instagram: `INSTAGRAM_COMPETITIVE` * Facebook: `FACEBOOK_COMPETITIVE` * YouTube: `YOUTUBE_COMPETITIVE` * Twitter (X): `TWITTER_COMPETITIVE` Use the `_COMPETITIVE` suffix for competitor reports.
`metrics` Metric to rank posts by. See [Metrics](#metrics) section below for all options. Request multiple metrics by separating with commas (e.g., `LIKES,TOTAL_ENGAGEMENTS,REACH`)
`competitor_source_account_ids` Comma-separated IDs from Step 1: `2306810931,230344968,232342925`
`start_date` / `end_date` Reporting period in `YYYY-MM-DDTHH:MM:SSZ` format (ISO 8601 with timezone)
`context_start_date` / `context_end_date` Comparison period for trend analysis in `YYYY-MM-DDTHH:MM:SSZ` format.
`report_type` Set to `COMPETITIVE_CONTENT` for this report
`limit` Number of posts to return per competitor. Defaults to 6 if not specified.
*** ### Step 3: Request the content report Send a GET request using the parameters from Step 2. This example gets top Facebook posts from tracked competitors during October 2025, ranked by likes: ```http theme={null} GET https://dashboard.dashsocial.com/reports/data?brand_ids=144& channels=FACEBOOK_COMPETITIVE& metrics=LIKES& start_date=2025-10-01T07:00:00Z& end_date=2025-10-30T07:00:00Z& context_start_date=2025-09-01T07:00:00Z& context_end_date=2025-09-30T07:00:00Z& report_type=COMPETITIVE_CONTENT& competitor_source_account_ids=2306810931,230344968,232342925 ``` ### Rank by multiple metrics Request multiple metrics by separating with commas (e.g., `LIKES,TOTAL_ENGAGEMENTS,REACH`). Posts will be ranked by each metric separately. Sample response: ```json theme={null} { "data": { "2306810931": { "avatar": "https://cdn.dashsocial.com/avatars/2306810931.jpeg", "content": [ { "id": "18123456789012345", "caption": "New fall collection drops tomorrow!", "created_at": "2025-10-15T14:22:00+00:00", "media_type": "IMAGE", "media_url": "https://cdn.dashsocial.com/media/12345.jpg", "permalink": "https://www.facebook.com/sunny.today/posts/123456", "metrics": { "LIKES": 1247, "COMMENTS": 89, "SHARES": 34, "TOTAL_ENGAGEMENTS": 1370 } } ], "data_type": "COMPETITOR", "name": "sunny.today", "user_has_access": false }, "230344968": { "avatar": "https://cdn.dashsocial.com/avatars/230344968.jpeg", "content": [ { "id": "18345678901234567", "caption": "Monday motivation: Your journey starts with a single step", "created_at": "2025-10-21T09:30:00+00:00", "media_type": "IMAGE", "media_url": "https://cdn.dashsocial.com/media/34567.jpg", "permalink": "https://www.facebook.com/scaniagroup/posts/345678", "metrics": { "LIKES": 2103, "COMMENTS": 156, "SHARES": 78, "TOTAL_ENGAGEMENTS": 2337 } } ], "data_type": "COMPETITOR", "name": "scaniagroup", "user_has_access": false } }, "product_category": "COMPETITIVE" } ``` *** ### Step 4: Interpret the response The response includes top-performing posts for each competitor, sorted by your chosen metric. #### Response structure Each competitor includes: * **`content`**: Array of posts, ranked highest to lowest by the selected metric * **`id`**: Unique post identifier from the social platform * **`caption`**: The post text/caption * **`created_at`**: When the post was published * **`media_type`**: Type of content (IMAGE, VIDEO, CAROUSEL, etc.) * **`media_url`**: URL to the media file * **`permalink`**: Direct link to the post on the social platform * **`metrics`**: Performance data for each post * **`name`**: The competitor's social media handle * **`avatar`**: URL to their profile picture * **`data_type`**: Always `COMPETITOR` for tracked competitor accounts **Common errors:** * **Invalid channel name** - Use `FACEBOOK_COMPETITIVE`, not `FACEBOOK`. Competitive channels require the `_COMPETITIVE` suffix. * **Invalid source account ID** - Verify IDs match the `/competitors/search` response from Step 1. * **Missing context dates** - Include `context_start_date` and `context_end_date` for trend analysis. *** ## Metrics | Metric Name | Description | Metric API Name | | --------------- | ------------------------------------------------------------------------------------------------ | ------------------ | | Engagement Rate | The percentage of people who engaged with your competitors' posts, based on their follower count | `ENGAGEMENT_RATE` | | Comments | The number of comments your competitors' posts received | `ORGANIC_COMMENTS` | | Likes | The number of likes your competitors' posts received | `ORGANIC_LIKES` | | Estimated Reach | The estimated number of unique accounts that saw your competitors' posts | `REACH` | | Metric Name | Description | Metric API Name | | --------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------- | | Comments | The number of comments your competitors' posts received | `COMMENTS` | | Engagement Rate | The percentage of people who engaged with your competitors' posts, based on their Page Fans | `ENGAGEMENT_RATE_PUBLIC` | | Likes | The number of likes your competitors' posts received | `LIKES` | | Reactions | The number of reactions your competitors' posts received. Reactions include Like, Love, Care, Haha, Wow, Sad and Angry. | `REACTIONS` | | Shares | The number of times your competitors' posts were shared | `SHARES` | | Engagements | The total number of engagements your competitors' posts received | `TOTAL_ENGAGEMENTS_PUBLIC` | | Metric Name | Description | Metric API Name | | ----------- | ------------------------------------------------------------------------ | --------------- | | Comments | The number of comments your competitors' posts received | `COMMENTS` | | Likes | The number of likes your competitors' posts received | `LIKES` | | Video Views | The number of times the videos on your competitors' channels were viewed | `VIDEO_VIEWS` | | Metric Name | Description | Metric API Name | | ------------- | ---------------------------------------------------------------------------- | --------------- | | Engagements | The total number of engagements your competitors' posts received | `ENGAGEMENTS` | | Likes | The number of likes your competitors' posts received | `LIKES` | | Quote Posts | The total number of times your competitors' posts were reposted with a quote | `QUOTE_POSTS` | | Replies | The total number of times your competitors' posts were replied to | `REPLIES` | | Reposts | The total number of times your competitors' posts were reposted | `REPOSTS` | | Total Reposts | The total number of times your competitors' posts were reposted | `TOTAL_REPOSTS` | | Video Views | The number of times your competitors' videos were viewed | `VIDEO_VIEWS` | ## Next steps With your competitive content data, you can: * **Inspire creative strategy** - Share top posts with your content team to identify successful themes and formats * **Benchmark performance** - Compare your best posts against competitor performance to set realistic engagement goals * **Track content trends** - Query weekly or monthly to spot emerging content trends in your industry * **Inform content calendar** - Analyze which post types and topics resonate to guide your publishing strategy Related guides: * [Compare Competitor Metrics Across Platforms](https://developer.dashsocial.com/guides/compare-competitor-metrics-across-platforms) * [Track Competitor Trends with Graph Reports](https://developer.dashsocial.com/guides/track-competitor-trends-with-graph-reports) * [View Full API Reference](https://developers.dashsocial.com/reference/get_reports-data) # Competitor report overview Source: https://developer.dashsocial.com/guides/reporting/export-dashboard-report-data-via-api/competitor-report/overview Track and benchmark public competitor activity across social platforms. Tracks public activity from competitor accounts you've added in Dash Social to benchmark performance and inform content strategy. **Available report types:** Compare Competitor Metrics Across Platforms Track Competitor Trends with Graph Reports Get Top Competitor Posts Ranked by Performance # Track competitor trends with graph reports Source: https://developer.dashsocial.com/guides/reporting/export-dashboard-report-data-via-api/competitor-report/track-competitor-trends-with-graph-reports Visualize competitor performance trends over time using time-series graph data. Pull time-series competitor data to track performance trends over time. Use the data to visualize day-by-day metrics and identify patterns in competitor activity. *** ## Use cases Tracking competitor trends manually across weeks or months wastes hours. Graph reports give you time-series data ready to visualize instantly. Track when competitors ramp up posting frequency to anticipate market moves or product launches Compare competitor performance trends on YouTube vs TikTok to guide your channel strategy Monitor seasonal patterns in competitor reach to inform your content calendar *** ## Before you start Prerequisites: * **API Key** - Your authentication token - Get your API key from the [API Quickstart](https://developer.dashsocial.com/guides/get-started/quickstart). * **Brand ID** - Your brand's unique ID * **Tracked Competitors** - Competitors added in Dash Social Supported platforms: * Instagram * Facebook * YouTube * X **Add competitors first:** Report on competitors tracked in Dash Social only. Add competitors in **Dash Social → Settings → Competitor Management** before using this API. ### Test in the dashboard first Preview competitive graph reports in the Dash Social Dashboard to understand the data structure before pulling via API. *** ## Implementation ### Step 1: Get competitor account IDs Get source account IDs for your tracked competitors. Each competitor has a unique ID per platform. Send a POST request: ```http theme={null} POST https://library-backend.dashsocial.com/competitors/search body = { "source": "INSTAGRAM" } ``` #### Key query parameters * `source`: Platform to search: * Instagram: `INSTAGRAM` * Facebook: `FACEBOOK` * YouTube: `YOUTUBE` * Twitter (X): `TWITTER` Sample response: ```json theme={null} [ { "avatar_url": "https://cdn.dashsocial.com/avatars/2306810931.jpeg", "brand_details": [ { "brand_id": 144, "created_at": "2019-10-22T21:02:14+00:00" } ], "handle": "sunny.today", "source": "INSTAGRAM", "source_account_id": "2306810931" }, { "avatar_url": "https://cdn.dashsocial.com/avatars/230344968.jpeg", "brand_details": [ { "brand_id": 144, "created_at": "2020-03-15T10:22:33+00:00" } ], "handle": "fashionista_brand", "source": "INSTAGRAM", "source_account_id": "230344968" } ] ``` Collect each `source_account_id` value. Format as comma-separated: `2306810931,230344968`. ### Compare across platforms To compare multiple platforms, call `/competitors/search` separately for each platform. *** ### Step 2: Map your report parameters Map the available parameters before making the API call:
Parameter Description
`brand_ids` Your brand ID.
`channels` Competitive channel to report on: * Instagram: `INSTAGRAM_COMPETITIVE` * Facebook: `FACEBOOK_COMPETITIVE` * YouTube: `YOUTUBE_COMPETITIVE` * Twitter (X): `TWITTER_COMPETITIVE` Use the `_COMPETITIVE` suffix for competitor reports.
`metrics` Metric to track over time. See [Metrics](#metrics) section below for all options. Request multiple metrics by separating with commas (e.g., `NUMBER_OF_POSTS,TOTAL_ENGAGEMENTS,REACH`)
`competitor_source_account_ids` Comma-separated IDs from Step 1: `2306810931,230344968,232342925`
`start_date` / `end_date` Reporting period in `YYYY-MM-DD` format. The graph report returns daily data points for each date in this range.
`context_start_date` / `context_end_date` Comparison date range for period-over-period analysis. Use same dates as `start_date` / `end_date` if no comparison needed
`report_type` Set to `COMPETITIVE_GRAPH` for time-series data
`time_scale` Time granularity for data aggregation: * `DAILY` - Daily data points (default) * `MONTHLY` - Monthly data points Optional. Defaults to `DAILY` if not specified.
*** ### Step 3: Request the graph report Send a GET request using the parameters from Step 2. This example gets daily engagement metrics for competitors on Instagram during October 2025: ```http theme={null} GET https://dashboard.dashsocial.com/reports/data?brand_ids=144& channels=INSTAGRAM_COMPETITIVE& metrics=TOTAL_ENGAGEMENTS& start_date=2025-10-01& end_date=2025-10-30& context_start_date=2025-09-01& context_end_date=2025-09-30& report_type=COMPETITIVE_GRAPH& competitor_source_account_ids=2306810931,230344968,232342925 ``` ### Compare multiple platforms Make separate requests for each channel: `INSTAGRAM_COMPETITIVE`, `FACEBOOK_COMPETITIVE`, etc. Combine results in your dashboard or analytics tool. Sample response: ```json theme={null} { "data": { "144": { "INSTAGRAM_COMPETITIVE": { "TOTAL_ENGAGEMENTS": { "2025-10-01": 0.0, "2025-10-02": 4.0, "2025-10-07": 27.0, "2025-10-08": 8.0 } }, "avatar": "https://cdn.dashsocial.com/avatars/2306810931.jpeg", "data_type": "BRAND", "name": "Your Brand", "user_has_access": true }, "2306810931": { "INSTAGRAM_COMPETITIVE": { "TOTAL_ENGAGEMENTS": { "2025-10-01": 120.0, "2025-10-02": 98.0, "2025-10-03": 145.0, "2025-10-05": 203.0 } }, "avatar": "https://cdn.dashsocial.com/avatars/2306810931.jpeg", "data_type": "COMPETITOR", "name": "sunny.today", "user_has_access": true }, "competitor_average": { "data_type": "COMPETITOR_AVERAGE", "name": "Competitor Average", "user_has_access": true } }, "product_category": "COMPETITIVE" } ``` *** ### Step 4: Interpret the response The response includes time-series data for each competitor plus a `competitor_average` summary. #### Response structure Each account includes: * **`data_type`**: `BRAND` (your brand), `COMPETITOR`, or `COMPETITOR_AVERAGE` * **`name`**: Account handle * **Date-keyed metrics**: Each metric is organized by date (e.g., `"2025-10-01": 120.0`). This makes it easy to plot on line charts or trend graphs. **Common errors:** * **Invalid channel name** - Use `INSTAGRAM_COMPETITIVE`, not `INSTAGRAM`. Competitive channels require the `_COMPETITIVE` suffix. * **Invalid source account ID** - Verify IDs match the `/competitors/search` response from Step 1. * **Missing context dates** - Include `context_start_date` and `context_end_date` for trend analysis. * **Sparse data** - Not all dates have values. Competitors only appear on dates when they posted content. *** ## Metrics | Metric Name | Description | Metric API Name | | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | | Avg. Engagement Rate - Public | The average percentage of people who engaged with your competitors' posts, based on their follower count | `AVG_ENGAGEMENT_RATE_PUBLIC` | | Avg. Estimated Reach | The average number of unique accounts that saw your posts published during the Reporting Period. The average estimated number of unique accounts that saw competitor's posts based on their number of followers during the Reporting Period. | `AVG_REACH` | | Followers - Growth Rate | The percentage of your competitors' followers increased by over the comparison period | `FOLLOWER_GROWTH_RATE` | | Followers - Net New | The net new number of people who followed your competitors' accounts | `NET_NEW_FOLLOWERS` | | Number of Posts | The number of posts you've published during the reporting period | `NUMBER_OF_POSTS` | | Comments | The number of comments your competitors' posts received | `ORGANIC_COMMENTS` | | Likes | The number of likes your competitors' posts received | `ORGANIC_LIKES` | | Followers | The total number of followers your competitors have on this channel | `TOTAL_FOLLOWERS` | | Metric Name | Description | Metric API Name | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | | Avg. Engagement Rate | The average engagement rate of your competitors' posts published during the Reporting Period. Engagement Rate = (Comments + Reactions + Shares) / Followers | `AVG_ENGAGEMENT_RATE_PUBLIC` | | Followers - Growth Rate | The percentage of your competitors' followers increased by over the comparison period | `FOLLOWER_GROWTH_RATE` | | Followers - Net New | The net new number of people who followed your competitors' accounts | `NET_NEW_FOLLOWERS` | | Number of Posts | The number of posts you've published during the reporting period | `NUMBER_OF_POSTS` | | Followers | The total number of followers your competitors have on this channel | `TOTAL_FOLLOWERS` | | Metric Name | Description | Metric API Name | | --------------------- | ------------------------------------------------------------------------------ | --------------------- | | Comments | The number of comments your competitors' posts received | `COMMENTS` | | Likes | The number of likes your competitors' posts received | `LIKES` | | Number of Posts | The number of posts your competitors published during the reporting period | `NUMBER_OF_POSTS` | | Subscribers - Net New | The net new number of people who have subscribed to your competitors' channels | `SUBSCRIBERS_NET_NEW` | | Subscribers | The total number of subscribers your competitors have on their channels | `SUBSCRIBERS_TOTAL` | | Video Views | The number of times the videos on your competitors' channels were viewed | `TOTAL_VIDEO_VIEWS` | | Metric Name | Description | Metric API Name | | ----------------------- | ---------------------------------------------------------------------------------- | ---------------------- | | Followers - Growth Rate | The percentage your competitors' followers increased by over the comparison period | `FOLLOWER_GROWTH_RATE` | | Likes | The number of likes your competitors' posts received | `LIKES` | | Followers - Net New | The net new number of people who followed your competitors' accounts | `NET_NEW_FOLLOWERS` | | Number of Posts | The number of posts your competitors published during the reporting period | `NUMBER_OF_POSTS` | | Quote Posts | The total number of times your competitors' posts were reposted with a quote | `QUOTE_POSTS` | | Replies | The total number of times your competitors' posts were replied to | `REPLIES` | | Reposts | The total number of times your competitors' posts were reposted | `REPOSTS` | | Engagements | The total number of engagements your competitors' posts received | `TOTAL_ENGAGEMENTS` | | Followers | The total number of followers your competitors have on this channel | `TOTAL_FOLLOWERS` | | Total Reposts | The total number of times your competitors' posts were reposted or quote posted | `TOTAL_RETWEETS` | | Video Views | The number of times your competitors' videos were viewed | `VIDEO_VIEWS` | ## Next steps With your competitive graph data, you can: * **Build trend visualizations** - Plot each competitor as a separate line on a chart * **Identify posting patterns** - Spot seasonal or weekly patterns in competitor activity * **Track peak performance days** - See when competitors get the most engagement * **Compare against your brand** - Benchmark your performance against competitor trends Related guides: * [Compare Competitor Metrics Across Platforms](https://developer.dashsocial.com/guides/compare-competitor-metrics-across-platforms) * [Get Top Competitor Posts Ranked by Performance](https://developer.dashsocial.com/guides/get-top-competitor-posts-ranked-by-performance) * [View Full API Reference](https://developers.dashsocial.com/reference/get_reports-data) # Get top UGC posts with content report Source: https://developer.dashsocial.com/guides/reporting/export-dashboard-report-data-via-api/earned-report/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. Watch Time | The average time that posts featuring you were played during a single viewing | `UGC_AVG_WATCH_TIME` | | UGC - Effectiveness | The 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 effectiveness. | `UGC_EFFECTIVENESS` | | UGC - Effectiveness | The percentage of people who saw posts featuring you and engaged with them | `UGC_EFFECTIVENESS_CONNECTED` | | 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 - Engagement Rate (Followers) | The 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_ENGAGEMENT_RATE` | | UGC - Engagement Rate (Views) | The 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_ENGAGEMENT_RATE_VIEWS` | | 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 - Comments | The number of comments on posts featuring you | `UGC_ORGANIC_COMMENTS` | | UGC - Likes | The number of likes received on posts featuring you | `UGC_ORGANIC_LIKES` | | 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 - 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_TOTAL_ENGAGEMENTS` | | 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 | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | | Completion Rate | The percentage of people who viewed the entire story featuring you. This metric is only available for reporting after March 24, 2025. | `COMPLETION_RATE` | | 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. | `EMV` | | 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` | | Exit Rate | 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. | `EXIT_RATE` | | Reach | The number of unique accounts who saw posts featuring you | `REACH` | | 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 times people tapped forward when viewing your story frames | `TAPS_FORWARD` | | 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 | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | | Comments | The number of comments on posts featuring you | `UGC_COMMENTS` | | 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` | | Engagement Rate | The percentage of people who engaged with posts featuring you, based on the number of people who viewed it | `UGC_ENGAGEMENT_RATE_VIEWS` | | Likes | The number of likes received on posts featuring you | `UGC_LIKES` | | Reach | The number of unique accounts who saw posts featuring you | `UGC_REACH` | | Shares | The number of times posts featuring you were shared | `UGC_SHARES` | | 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. | `UGC_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) # Measure UGC performance metrics Source: https://developer.dashsocial.com/guides/reporting/export-dashboard-report-data-via-api/earned-report/measure-ugc-performance-metrics Pull aggregated user-generated content metrics to measure earned media impact across Instagram and TikTok. 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 access token** with permissions to the relevant brand. * **Brand ID** for the account you want to query. See [API Quickstart](/guides/get-started/quickstart) for more details. **Supported platforms** This report supports these UGC channels: * Instagram * Instagram Stories * TikTok **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 if no comparison needed
`report_type` Set to `TOTAL_METRIC` for aggregated totals
*** ### Step 2: Make the API call Send a GET request using the parameters from Step 1. This example pulls total comments on Instagram UGC mentioning brand `144` from August 10-20, with July 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_COMMENTS &report_type=TOTAL_METRIC ``` ### 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 totals for each metric, organized by brand and channel. The `value` field shows your reporting period total. The `context` field shows your comparison period total. ```json theme={null} { "data": { "144": { "avatar": "https://cdn.dashsocial.com/avatars/2306810931.jpeg", "data_type": "BRAND", "metrics": { "UGC_COMMENTS": { "INSTAGRAM_UGC": { "context": 6.0, "context_change": -0.8333333333333334, "value": 1.0 } } }, "name": "sunny.today", "user_has_access": true } }, "product_category": "UGC" } ``` **Understanding the response:** Metrics are organized by brand ID and channel. Brand `144` ("sunny.today") received 1 comment on Instagram UGC during the reporting period (August 10-20), down from 6 comments in the context period (July 1-31). The `context_change` value of -0.833 indicates an 83.3% decrease. *** ## 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) # Earned report overview Source: https://developer.dashsocial.com/guides/reporting/export-dashboard-report-data-via-api/earned-report/overview Track UGC and brand mentions across your earned media channels. Tracks brand mentions in user-generated content and creator posts to measure influencer ROI and earned media value. **Available report types:** Measure UGC Performance Metrics Track UGC Performance Trends with Graph Report Get Top UGC Posts with Content Report # Track UGC performance trends with graph report Source: https://developer.dashsocial.com/guides/reporting/export-dashboard-report-data-via-api/earned-report/track-ugc-performance-trends-with-graph-report Visualize time-series trends in brand mentions and UGC engagement over time. Track how UGC and creator content mentioning your brand performs over time. Pull daily or monthly time-series data for brand mentions to visualize trends in BI tools like Power BI, Tableau, or Looker. *** ## Use cases Graph reports give you day-by-day or month-by-month breakdowns of UGC metrics. This makes it easy to spot trends, measure campaign momentum, and visualize creator impact over time. Chart daily UGC reach and engagement during influencer campaigns to measure impact and optimize future partnerships Visualize monthly UGC volume and engagement patterns to identify peak seasons for brand mentions Track time-series UGC metrics in Tableau to measure ongoing creator partnership value and justify budgets *** ## Before you start Make sure you have: * **API access token** with permissions to the relevant brand. * **Brand ID** for the account you want to query. See [API Quickstart](/guides/get-started/quickstart) for more details. **Supported platforms** This report supports these UGC channels: * Instagram * Instagram Stories * TikTok **About graph reports** Graph reports return time-series data with values for each date rather than aggregated totals. Choose daily (default) or monthly granularity using the `time_scale` parameter. **Test in the UI first:** Create a Dashboard in the Dash Social UI and configure your Graph report there. This previews the metrics and time scale behavior 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 track over time (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 if no comparison needed
`report_type` Set to `GRAPH` for time-series data
`time_scale` *(optional)* Choose `DAILY` (default) or `MONTHLY` granularity
*** ### Step 2: Make the API call Send a GET request using the parameters from Step 1. This example pulls daily comments on Instagram UGC mentioning brand `144` from August 10-20, with July 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_COMMENTS &report_type=GRAPH ``` ### 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 a time-series breakdown with values for each date. The response structure is: `brand_id` → `channel` → `metric` → `date` → `value`. ```json theme={null} { "data": { "144": { "INSTAGRAM_UGC": { "UGC_COMMENTS": { "2025-08-18": 0.0, "2025-08-19": 0.0, "2025-08-20": 1.0, "2025-08-21": 0.0 } }, "avatar": "https://cdn.dashsocial.com/avatars/2306810931.jpeg", "data_type": "BRAND", "metrics": { "UGC_COMMENTS": { "INSTAGRAM_UGC": { "2025-08-18": 0.0, "2025-08-19": 0.0, "2025-08-20": 1.0, "2025-08-21": 0.0 } } }, "name": "sunny.today", "user_has_access": true } }, "product_category": "UGC" } ``` **Understanding the response:** In this example, brand `144` ("sunny.today") received 1 comment on Instagram UGC on August 20, with 0 comments on surrounding dates. Use this time-series data in BI tools like Power BI, Tableau, or Looker to visualize trends. *** ## 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 time-series UGC performance data per brand and platform. Use this data to: * **Visualize trends** - Chart daily or monthly UGC metrics in BI tools * **Measure campaigns** - Track performance momentum during influencer campaigns * **Identify patterns** - Spot seasonal trends and peak engagement periods **Related guides:** * [Measure Aggregated UGC Metrics →](/guides/track-ugc-metrics-for-brand-mentions) * [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) # Export dashboard report data via API Source: https://developer.dashsocial.com/guides/reporting/export-dashboard-report-data-via-api/index Export Dash Social dashboard analytics using the reports API endpoint. The Dashboard Reports API lets you export the same analytics data available in the Dash Social UI using a single endpoint: ```http theme={null} GET https://dashboard.dashsocial.com/reports/data ``` To successfully retrieve data, you must choose: 1. **Data source** – Where the data comes from (Owned, Competitive, Earned, etc.) 2. **Output format** – How the data is structured (Metric, Graph, or Content) These two decisions determine: * What data is returned * Which metrics are available * The shape of the JSON response * How your integration parses the results This guide helps you select the correct combination before building your API request. *** ## Use case examples * Sync monthly engagement totals to a data warehouse * Export competitor metrics for benchmarking dashboards * Track influencer campaign performance * Monitor response time metrics for customer support * Build time-series charts in Tableau or Looker *** ## How the endpoint works All Dashboard reports are requested from the same endpoint: ```http theme={null} GET https://dashboard.dashsocial.com/reports/data ``` Your query parameters define what the API returns. Key parameters include: * `data_source` – Owned, Competitive, Earned, Community, Social Listening, or Total Social Impact * `report_type` – Output structure (`TOTAL_METRIC`, `GRAPH`, or `CONTENT`) * `metrics` – Metrics to retrieve * `channels` – Social platforms (e.g., INSTAGRAM, TIKTOK, FACEBOOK) * `brand_ids` – Brands to report on * `start_date` / `end_date` – Reporting period * `context_start_date` / `context_end_date` – Comparison period Different combinations return different response schemas. Choose carefully—your parsing logic depends on it. *** ## Data sources (what you're measuring) Each data source pulls from a different dataset. | Data Source | What It Includes | Common Use Cases | | ------------------------------------------------------------------------------------- | ----------------------------------------- | --------------------------------------- | | [**Owned**](https://developer.dashsocial.com/docs/owned-report) | Content published by your brand | Campaign reporting, BI exports | | [**Competitive**](https://developer.dashsocial.com/docs/competitor-report) | Public competitor posts | Benchmarking, market analysis | | [**Earned**](https://developer.dashsocial.com/docs/earned-report) | Creator and UGC brand mentions | Influencer ROI, earned media tracking | | [**Community**](https://developer.dashsocial.com/docs/community-report) | Your team's responses to comments and DMs | Support metrics, response time tracking | | [**Social Listening**](https://developer.dashsocial.com/docs/social-listening-report) | Conversations matching keyword searches | Brand sentiment, hashtag monitoring | | [**Total Social Impact**](https://developer.dashsocial.com/docs/tsi-report) | Combined owned + earned score | Executive reporting, unified KPIs | Your selected data source affects: * Available metrics * Channel support * Required filters * Data availability *** ## Output formats (how the data is structured) After selecting a data source, choose how the API should return the data. Important: The definition and date basis of each metric does not change across formats. Only the structure of the response changes. ### Understanding metric types Metrics fall into different categories, and the category determines how values are calculated and grouped. * **Account-level metrics** represent overall activity across your account during the reporting period. For example, total engagements across all posts. * **Post-level metrics** represent performance tied to specific posts. These are typically grouped by the post's publish date. * **UGC metrics** represent performance of content that tags or mentions your brand. Always confirm whether your selected metric is publish-based or activity-based before interpreting totals or trends. ### Metric format (`TOTAL_METRIC`) Returns a single aggregated value for one metric. Use this when you need: * KPI snapshots * Monthly or quarterly totals * Simple executive dashboards **Example response:** ```json theme={null} { "data": { "144": { "avatar": "https://cdn.dashsocial.com/avatars/2306810931.jpeg", "data_type": "BRAND", "metrics": { "VIEWS": { "INSTAGRAM": { "context": 270.0, "context_change": 0.5111111111111111, "value": 408.0 } } }, "name": "sunny.today", "user_has_access": true } }, "product_category": "OWNED" } ``` ### Graph format (`GRAPH`) Returns metric grouped by date, with daily or monthly breakdowns. For account-level metrics, values reflect activity that occurred on each date in the reporting period. For post-level metrics, values are grouped by the publish date of posts within the reporting window. Use this when you need: * Trend analysis * BI dashboards * Performance comparisons across time periods **Example response:** ```json theme={null} { "data": { "144": { "INSTAGRAM": { "VIEWS": { "2025-05-01": 205.0, "2025-05-04": 13.0, "2025-05-05": 11.0, "2025-05-06": 11.0, "2025-05-07": 51.0, "2025-05-08": 117.0 } }, "avatar": "https://cdn.dashsocial.com/avatars/2306810931.jpeg", "data_type": "BRAND", "metrics": { "VIEWS": { "INSTAGRAM": { "2025-05-01": 205.0, "2025-05-04": 13.0, "2025-05-05": 11.0, "2025-05-06": 11.0, "2025-05-07": 51.0, "2025-05-08": 117.0 } } }, "name": "sunny.today", "user_has_access": true } }, "product_category": "OWNED" } ``` ### Content format (`CONTENT`) Returns individual posts ranked by a selected metric, including metadata. Use this when you need: * Top-performing posts * Creative analysis * Post-level exports **Example response:** ```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": 823836824, "caption_question": { "is_question": true, "user_overridden": false }, "caption_sentiment": { "is_negative": false, "is_neutral": true, "is_positive": false, "user_overridden": false }, "collections": { "boards": { "facebook": null, "instagram": null, "instagram_story": null, "linkedin": null, "pinterest": null, "threads": null, "tiktok": null, "twitter": null, "youtube": null }, "campaigns": [ 49324 ], "galleries": null }, "comment_sentiment": null, "community_engagement": null, "content_tags": null, "created_at": "2025-05-01T14:16:10", "custom_metrics": [ { "id": 1991, "value": 0.0 } ], "facebook": null, "id": 527602428, "instagram": { "ad_account_scoped_insights": null, "ad_ids": null, "adset_ids": null, "amount_spent": null, "avg_time_viewed_sec": 2, "campaign_ids": null, "caption": "May 1st thumbnails", "clicks": null, "comments_count": 0, "cost_per_thruplay": null, "cpc": null, "cpm": null, "ctr": null, "effectiveness": 0.0, "effectiveness_engagements": 0.0, "emv": 300.335, "engagement": 0.0, "engagement_rate_impressions": 0.0, "engagement_rate_public": 0.0, "engagement_rate_views": 0.0, "engagements_public": 0, "entertainment_score": 0.0010660980810234544, "followers_gained": null, "follows": null, "hashtags": [], "impressions": 0, "is_boosted": false, "is_carousel": false, "is_commented": false, "is_mentioned": false, "is_riq": false, "is_tagged": false, "like_count": 0, "paid_and_organic_reach": 3, "paid_and_organic_saved": 0, "paid_and_organic_shares": 0, "paid_comments": 0, "paid_engagement_rate": 0.0, "paid_impressions": 0, "paid_likes": 0, "paid_reach": null, "paid_reactions": null, "paid_saved": 0, "paid_shares": null, "paid_total_engagement": 0, "paid_total_engagements": 0, "paid_video_views": 0, "photo_tags": [], "post_type": "reel", "profile_activity": { "bio_link_clicked": 0, "direction": 0, "email": 0, "other": 0, "text": 0, "total": 0 }, "profile_visits": null, "public_views": null, "reach": 3, "replays": 0, "saved": 0, "shares": 0, "sum_total_engagement": 0, "sum_total_engagements": 0, "thruplays": null, "timestamp": "2025-05-01T14:15:31+00:00", "total_comments": 0, "total_engagement": 0, "total_impressions": 0, "total_likes": 0, "total_plays": 0, "total_time_viewed_sec": 3, "total_time_viewed_sec_long": 3, "total_video_views": 0, "url": "https://www.instagram.com/reel/DJHPSMbvHe5/", "video_plays_100": null, "video_plays_25": null, "video_plays_50": null, "video_plays_75": null, "video_views": 0, "views": 4 }, "instagram_ads": null, "instagram_story_frame": null, "likeshop": { "clicks": 0, "links": null, "tiktok_clicks": null }, "linkedin": null, "media_group": 517557159, "meta": {}, "pinterest": null, "predictions": { "engagement": 0.7505790489596662 }, "snapchat": null, "source": "INSTAGRAM", "source_account_id": "2306810931", "source_created_at": "2025-05-01T14:15:31", "source_id": "18106727113450385", "source_type": "OWNED", "threads": null, "tiktok": null, "tiktok_ad": null, "twitter": null, "type": "VIDEO", "variants": [], "video": { "duration": 18.0, "frame_rate": 30.0, "sizes": { "original": { "height": 720, "size": 1430441, "url": "https://cdn.dashsocial.com/media/original/1746108968.853499289953.mp4", "width": 720 }, "original_converted": { "height": 720, "size": 1430441, "url": "https://cdn.dashsocial.com/media/full/1758827691.34561998805.mp4", "width": 720 } }, "thumbnails": { "medium_square": { "height": 640, "url": "https://images.dashsocial.com/aHR0cHM6Ly9jZG4uZGFzaHNvY2lhbC5jb20vbWVkaWEvZnVsbC8xNzQ2MTA4OTY5LjQ5MTQ1MTU1MzM0NS5qcGVn.jpg?w=640&h=640&fit=cover", "width": 640 }, "original_converted": { "height": 720, "size": 48322, "url": "https://cdn.dashsocial.com/media/full/1746108969.491451553345.jpeg", "width": 720 }, "small": { "height": 400, "url": "https://images.dashsocial.com/aHR0cHM6Ly9jZG4uZGFzaHNvY2lhbC5jb20vbWVkaWEvZnVsbC8xNzQ2MTA4OTY5LjQ5MTQ1MTU1MzM0NS5qcGVn.jpg?w=400&h=400", "width": 400 }, "small_square": { "height": 400, "url": "https://images.dashsocial.com/aHR0cHM6Ly9jZG4uZGFzaHNvY2lhbC5jb20vbWVkaWEvZnVsbC8xNzQ2MTA4OTY5LjQ5MTQ1MTU1MzM0NS5qcGVn.jpg?w=400&h=400&fit=cover", "width": 400 } } }, "youtube": null } ] }, "product_category": "OWNED" } ``` *** ## Choosing the right combination Use these common patterns: * Track your own content performance → Owned + Content * Compare against competitors → Competitive + Graph * Pull a KPI total → Any data source + Metric * Build time-based dashboards → Any data source + Graph * Analyze influencer performance → Earned + Graph or Metric *** ## Test in the UI first Before writing code: 1. Create a Dashboard in the Dash Social UI 2. Configure your filters and metrics 3. Confirm the data structure and values The API parameters mirror the UI configuration. Testing in the UI helps validate your selections before implementing the request. *** ## Final outcome After choosing the correct data source and format, you can: * Export structured JSON aligned with your reporting needs * Sync data to BI tools or internal dashboards * Store consistent schemas in your data warehouse * Avoid reworking parsing logic later *** ## Next steps * Review the full Dashboard Reports API reference * See individual guides for Owned, Competitive, or Earned reports * Build your first request using a test brand and date range * Automate recurring exports for scheduled reporting workflows # Get top-performing posts with content report Source: https://developer.dashsocial.com/guides/reporting/export-dashboard-report-data-via-api/owned-report/get-top-performing-posts-with-content-report Rank brand posts by performance metrics and identify top performers using the content report. Rank your brand's posts by any performance metric. Use this to surface top performers, analyze what works, and measure campaign impact. *** ## Use cases Manual performance reviews take hours. The Content report ranks posts automatically, letting you identify top performers in seconds. Surface the top 10 posts from your holiday campaign to show stakeholders what drove results Identify your highest-performing Reels to guide creative strategy and content planning Compare top posts by reach vs. engagement to understand what formats work best *** ## Before you start Make sure you have: * **API access token** with permissions to the relevant brand. * **Brand ID** for the account you want to query. See [API Quickstart](/guides/get-started/quickstart) for more details. **Supported platforms** This report supports these channels: * Instagram (including Stories) * TikTok * Facebook * Pinterest * YouTube * LinkedIn * X **About content reports** Content reports return individual posts ranked by your chosen metric. You get a list of posts sorted by performance (like top 10 by engagement). No aggregated totals or time-series data. Perfect for identifying what content resonates most. **Need all post metrics instead of top performers?** The Content report is designed to surface your best-performing posts, not export all posts. If you need metrics for every post in a date range, use the [media/v2 endpoint](/guides/reporting/get-post-performance-data-across-all-channels) instead. **Brand-owned content only:** This report only returns posts published by your brand accounts. UGC and tagged posts are not included. **Test in the UI first:** Create a Content report in the Dash Social Dashboard UI to preview channel and metric combinations before writing code. *** ## 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., `12345,67890`)
`channels` Social platforms to include: * Instagram: `INSTAGRAM` * Instagram Stories: `INSTAGRAM_STORIES` * TikTok: `TIKTOK` * Facebook: `FACEBOOK` * Pinterest: `PINTEREST` * YouTube: `YOUTUBE` * LinkedIn: `LINKEDIN` * X: `TWITTER`
`metrics` Metric to rank posts by. See [Available Metrics](#metrics) section below for all options. Request multiple metrics by separating with commas (e.g., `TOTAL_ENGAGEMENTS,REACH,VIEWS`)
`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. Use same dates if no comparison needed
`report_type` Set to `CONTENT` for ranked post lists
`limit` Number of posts to return. Defaults to 6 if not specified
*** ### Step 2: Make the API call Send a GET request using the parameters from Step 1. This example pulls the top Instagram post ranked by total engagements from May 1-7, with April 1-7 as the comparison period. ```http theme={null} GET https://dashboard.dashsocial.com/reports/data ?channels=INSTAGRAM &brand_ids=12345 &start_date=2025-05-01 &end_date=2025-05-07 &context_start_date=2025-04-01 &context_end_date=2025-04-07 &metrics=TOTAL_ENGAGEMENTS &report_type=CONTENT &limit=1 ``` **How posts are ranked:** Posts automatically sort by the first metric you specify. If you request `TOTAL_ENGAGEMENTS,REACH,VIEWS`, posts rank by total engagements. The response includes all three metrics for each post. **Date format matters:** Always use `YYYY-MM-DD` format for dates (e.g., `2025-05-01`). Other formats will cause errors. **Common errors:** * **400 error** - Check that dates are in `YYYY-MM-DD` format, metrics are valid for your channel, and brand\_id exists * **Invalid date format** - Use `YYYY-MM-DD` format. `2025-05-01` works, `05/01/2025` doesn't * **Missing brand ID** - Verify your brand ID is correct. Get it from your account settings #### Sample response The API returns ranked posts organized by brand. Each post includes caption, media URL, permalink, and all requested metrics. ```json theme={null} { "data": { "12345": { "avatar": "https://cdn.dashsocial.com/avatars/12345.jpeg", "content": [ { "id": "18123456789012345", "caption": "Our new spring collection drops tomorrow! 🌸 Which piece is your favorite?", "created_at": "2025-05-05T14:22:00+00:00", "media_type": "IMAGE", "media_url": "https://cdn.dashsocial.com/media/12345.jpg", "permalink": "https://www.instagram.com/p/Abc123/", "metrics": { "TOTAL_ENGAGEMENTS": 2847, "LIKES": 2456, "COMMENTS": 312, "SHARES": 79, "REACH": 18934, "IMPRESSIONS": 24012 } } ], "data_type": "OWNED", "name": "yourbrand", "user_has_access": true } }, "product_category": "OWNED" } ``` **Understanding the response:** Posts are sorted by the metric you selected (total engagements in this example). Brand `12345` ("yourbrand") top post had 2,847 total engagements during May 1-7. The response includes the post's media URL, permalink, and all engagement metrics. *** ## Metrics | Metric Name | Description | Post Types | Metric API Name | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | --------------------------- | | Ad Engagements - Paid | The total number of ad engagements your promoted posts received | Promoted | `AD_ENGAGEMENTS` | | Amount Spent - Paid | The total amount of money you've spent boosting your posts. Due to API delays, recent spend figures may be estimated for up to 48 hours. | Promoted | `AMOUNT_SPENT` | | Avg. Time Watched - Organic | The average time your videos were played during a single viewing | Organic | `AVG_TIME_WATCHED` | | Clicks - Paid | The number of clicks received on your posts. This can include link clicks, clicks to your profile and more. | Promoted | `CLICKS` | | Cost per ThruPlay - Paid | The average cost per Thruplay for your videos | Promoted | `COST_PER_THRUPLAY` | | CPC - Paid | The average cost per click on your promoted posts | Promoted | `CPC` | | CPM - Paid | The average cost per 1,000 impressions on your promoted posts | Promoted | `CPM` | | Views - Crossposted - Organic | Total views across Instagram and Facebook for content crossposted natively between platforms. For Reels, includes views from crossposting or cross-app recommendations, where Reels appear on Facebook under your Instagram username. | Organic | `CROSSPOSTED_VIEWS` | | CTR - Paid | The percentage of times people clicked your promoted posts after seeing them | Promoted | `CTR` | | Effectiveness - Organic | The percentage of viewers who saw your posts and engaged with them | Organic | `EFFECTIVENESS_ENGAGEMENTS` | | Engagement Rate (Followers) - Organic | The percentage of people who engaged with your posts after seeing them | Organic | `ENGAGEMENT_RATE` | | Engagement Rate (Views) - Organic | The percentage of people who engaged with your posts after seeing them | Organic | `ENGAGEMENT_RATE_VIEWS` | | Entertainment Score | The Entertainment Score for Reels is on a scale of 0 to 10 and is based on volume of organic engagements compared to reach. | Organic | `ENTERTAINMENT_SCORE` | | Views - Facebook - Organic | The number of views your posts received on Facebook, for content crossposted natively from Instagram. For Reels, also includes views from cross-app recommendations, where Reels appear on Facebook under your Instagram username. | Organic | `FACEBOOK_VIEWS` | | Follows - Organic | The number of accounts that started following you after viewing your post | Organic | `FOLLOWS` | | LikeShop Clicks | The total number of clicks on any LikeShop feed products during the reporting period | | `LIKESHOP_CLICKS` | | Comments - Organic | The number of comments on your posts published during the reporting period | Organic | `ORGANIC_COMMENTS` | | Likes - Organic | The number of likes received on posts published during the reporting period | Organic | `ORGANIC_LIKES` | | Views - Organic | The number of times your posts were viewed or displayed | Organic | `ORGANIC_VIEWS` | | Reach - Total | The number of unique accounts that saw your posts | Organic + Promoted | `PAID_AND_ORGANIC_REACH` | | Saves - Total | The number of times your posts were saved | Organic + Promoted | `PAID_AND_ORGANIC_SAVES` | | Shares - Total | The number of times your posts were shared | Organic + Promoted | `PAID_AND_ORGANIC_SHARES` | | Comments - Paid | The number of comments your posts received | Promoted | `PAID_COMMENTS` | | Engagement Rate (Impressions) - Paid | The promoted engagement rate on your posts this period | Promoted | `PAID_ENGAGEMENT_RATE` | | Impressions - Paid | The number of times your posts were viewed or displayed | Promoted | `PAID_IMPRESSIONS` | | Likes - Paid | The number of likes your posts received | Promoted | `PAID_LIKES` | | Reach - Paid | The number of unique accounts that saw your posts | Promoted | `PAID_REACH` | | Saves - Paid | The number of times your posts were saved | Promoted | `PAID_SAVES` | | Shares - Paid | The number of times your posts were shared | Promoted | `PAID_SHARES` | | Engagements - Paid | The total number of engagements your posts received | Promoted | `PAID_TOTAL_ENGAGEMENTS` | | Video Views - Paid | The number of times your videos were viewed | Promoted | `PAID_VIDEO_VIEWS` | | Profile Clicks - Organic | The number of actions people take when they visit your profile after viewing your post. This can include bio link clicks, calls, emails, and more. | Organic | `PROFILE_CLICKS` | | Profile Bio Link Clicks | The number of times people clicked the link in your profile bio after viewing your post | Organic | `PROFILE_CLICKS_BIO` | | Profile Call Clicks - Organic | The number of times people tapped the call button on your profile after viewing your posts | Organic | `PROFILE_CLICKS_CALL` | | Profile Directions Clicks - Organic | The number of times people clicked to get directions from your profile after viewing your posts | Organic | `PROFILE_CLICKS_DIRECTIONS` | | Profile Email Clicks | The number of times people tapped the email button on your profile after viewing your posts | Organic | `PROFILE_CLICKS_EMAIL` | | Profile Other Clicks - Organic | The number of times people clicked other profile buttons after viewing your posts | Organic | `PROFILE_CLICKS_OTHER` | | Profile Text Clicks | The number of times people tapped the text message button on your profile after viewing your posts | Organic | `PROFILE_CLICKS_TEXT` | | Profile Visits - Organic | The number of times your profile was visited after viewing your post | Organic | `PROFILE_VISITS` | | Reach - Organic | The number of unique accounts that saw your posts | Organic | `REACH` | | Skip Rate - Organic | The percentage of viewers who skipped your Reels within the first 3 seconds | Organic | `REELS_SKIP_RATE` | | Reposts - Organic | The number of times your posts have been reposted | Organic | `REPOSTS` | | Saves - Organic | The number of times your posts published during the reporting period were saved | Organic | `SAVES` | | Shares - Organic | The number of times your posts published were shared during the reporting period | Organic | `SHARES` | | Engagements - Total | The total number of engagements from all posts published during the Reporting Period | Organic + Promoted | `SUM_TOTAL_ENGAGEMENTS` | | ThruPlays - Paid | The number of times your posts were watched to completion or for at least 15 seconds | Promoted | `THRUPLAYS` | | Comments - Total | The number of comments your posts received | Organic + Promoted | `TOTAL_COMMENTS` | | Engagements - Organic | The total number of engagements on your posts published during the reporting period Engagements = (Likes + Saves + Comments + Shares) - (Unlikes + Unsaves + Deleted comments) | Organic | `TOTAL_ENGAGEMENTS` | | Likes - Total | The number of likes your posts received | Organic + Promoted | `TOTAL_LIKES` | | Video Plays 100% - Paid | The number of times your video was played to 100% of its length, including plays that skipped to this point | Promoted | `VIDEO_PLAYS_100` | | Video Plays 25% - Paid | The number of times your video was played to 25% of its length, including plays that skipped to this point | Promoted | `VIDEO_PLAYS_25` | | Video Plays 50% - Paid | The number of times your video was played to 50% of its length, including plays that skipped to this point | Promoted | `VIDEO_PLAYS_50` | | Video Plays 75% - Paid | The number of times your video was played to 75% of its length, including plays that skipped to this point | Promoted | `VIDEO_PLAYS_75` | | Total Time Watched - Organic | The sum of the time that all viewers watched your videos for | Organic | `WATCH_TIME` | | Metric Name | Description | Post Types | Metric API Name | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------------------ | | Avg. Completion Rate | The average percentage of people who viewed the entire story. Completion Rate = (Exits - Views) / Views. This metric is only available for reporting after March 24, 2025. | Organic | `AVG_COMPLETION_RATE_VIEWS` | | Avg. Exit Rate | The percentage of people who exited out of the story. Exit Rate = Exits / Views. This metric is only available for reporting after March 24, 2025. | Organic | `AVG_EXIT_RATE_VIEWS` | | Avg. Reach | The average number of unique accounts that saw your stories published during the Reporting Period. | Organic | `AVG_REACH` | | Avg. Views | The average number of times that frames in your Stories were viewed or displayed | Organic | `AVG_VIEWS` | | Completion Rate | The percentage of people who completed your Stories | Organic | `STORY_FRAMES_COMPLETION_RATE_VIEWS` | | Exit Rate | The percentage of people who exited out of your Stories | Organic | `STORY_FRAMES_EXIT_RATE_VIEWS` | | Reach | The number of unique accounts that saw your Stories | Organic | `STORY_FRAMES_REACH` | | Stories Link Clicks | The total number of link clicks on your story frames. Only links scheduled through the Dash scheduler are trackable in Dash Social. | Organic | `STORY_FRAMES_SWIPE_UPS` | | Views | The number of times that frames in your Stories were viewed or displayed | Organic | `STORY_FRAMES_VIEWS` | | Stories Link Clicks | The number of link clicks on the story frames published during during the reporting period. Only links scheduled through Dash are trackable via the platform. | Organic | `SWIPE_UPS` | | Metric Name | Description | Post Types | Metric API Name | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----------------------------------- | | Avg. Time Watched - Total | The average amount of time viewers spent watching your organic and promoted videos published during the reporting period | Organic + Promoted | `AVG_TIME_WATCHED` | | Completion Rate - Total | The percentage of viewers that watched your videos to completion | Organic + Promoted | `COMPLETION_RATE` | | Engagement Rate (Reach) - Total | The percentage of people who engaged with your posts after seeing them | Organic + Promoted | `ENGAGEMENT_RATE` | | Entertainment Score - Total | The TikTok Entertainment Score is on a scale of 0 to 10 and takes the engagement and retention rate of each video into account. Scores are generated 48 hours after publishing. | Organic + Promoted | `ENTERTAINMENT_SCORE` | | Favorites - Total | The total number of times your posts have been added to favorites | Organic + Promoted | `FAVORITES` | | Follows - Total | The number of viewers who started following you after viewing your posts | Organic + Promoted | `FOLLOWS` | | Traffic - Following Page - Total | The percentage of your posts' video views that originated from a user's Following Page | Organic + Promoted | `IMPRESSIONS_FOLLOW_RATE` | | FYP Views % - Total | The average percentage of video views that came from the For You page | Organic + Promoted | `IMPRESSIONS_FOR_YOU_RATE` | | Traffic - Hashtag - Total | The percentage of your posts' video views that originated from viewing a Hashtag | Organic + Promoted | `IMPRESSIONS_HASHTAG_RATE` | | Traffic - Personal Profile - Total | The percentage of your posts' video views that originated from your Profile | Organic + Promoted | `IMPRESSIONS_PERSONAL_PROFILE_RATE` | | Traffic - Search - Total | The percentage of your posts' video views that originated from Search | Organic + Promoted | `IMPRESSIONS_SEARCH_RATE` | | Traffic - Sound - Total | The percentage of your posts' video views that originated from viewing a Sound | Organic + Promoted | `IMPRESSIONS_SOUND_RATE` | | LikeShop Clicks | The number of clicks on your products on your LikeShop feed | | `LIKESHOP_CLICKS` | | Follows - Organic | The number of viewers who started following you after viewing your posts. Important: This metric stops updating when ad promotions end. | Organic | `ORGANIC_FOLLOWS` | | Likes - Organic | The number of likes any of your organic and promoted videos received during the reporting period | Organic | `ORGANIC_LIKES` | | Profile Views - Organic | The number of profile views generated by your posts. Important: This metric stops updating when ad promotions end. Data may be delayed by 48 hours. | Organic | `ORGANIC_PROFILE_VIEWS` | | Reach - Est. Organic | The number of unique accounts that saw your posts | ESTIMATED\_ORGANIC | `ORGANIC_REACH` | | Shares - Organic | The number of times your posts were shared | Organic | `ORGANIC_SHARES` | | Video Views - Est. Organic | The number of times your videos were viewed | ESTIMATED\_ORGANIC | `ORGANIC_VIDEO_VIEWS` | | Engagements - Paid | The total number of engagements your posts received | Promoted | `PAID_ENGAGEMENTS` | | Engagement Rate (Reach) - Paid | The percentage of people who engaged with your posts after seeing them | Promoted | `PAID_ENGAGEMENT_RATE` | | Follows - Paid | The number of viewers who started following you after viewing your posts. Important: This metric stops updating when ad promotions end. | Promoted | `PAID_FOLLOWS` | | Likes - Paid | The number of likes your posts received | Promoted | `PAID_LIKES` | | Profile Views - Paid | The number of profile views generated by your posts. Important: This metric stops updating when ad promotions end. Data may be delayed by 48 hours. | Promoted | `PAID_PROFILE_VIEWS` | | Reach - Paid | The number of unique accounts that saw your posts | Promoted | `PAID_REACH` | | Shares - Paid | The number of times your posts were shared | Promoted | `PAID_SHARES` | | Video Views - Paid | The number of times your videos were viewed | Promoted | `PAID_VIDEO_VIEWS` | | Engagement Rate (Views) - Paid | The percentage of people who engaged with your posts after seeing them | Promoted | `PAID_VIEWS_BASED_ENGAGEMENT_RATE` | | Profile Views - Total | The total number of profile views generated by your posts. Data may be delayed by 48 hours. | Organic + Promoted | `PROFILE_VIEWS` | | Reach - Total | The number of unique accounts that saw your posts | Organic + Promoted | `REACH` | | Retention Rate - Total | The average percentage of your videos that people watched | Organic + Promoted | `RETENTION_RATE` | | Comments - Total | The number of comments your organic and promoted videos published during the reporting period received | Organic + Promoted | `TOTAL_COMMENTS` | | Engagements - Total | The number of engagements your organic and promoted videos published during the reporting period received Total Engagements = Likes + Comments + Shares | Organic + Promoted | `TOTAL_ENGAGEMENTS` | | Likes - Total | The number of likes your organic and promoted videos published during the reporting period received | Organic + Promoted | `TOTAL_LIKES` | | Shares - Total | The number of times your posts published during the reporting period were shared | Organic + Promoted | `TOTAL_SHARES` | | Time Watched - Total | The total amount of time viewers spent watching your videos | Organic + Promoted | `TOTAL_TIME_WATCHED` | | Video Views - Total | The number of times your organic and promoted videos published during the reporting period were viewed | Organic + Promoted | `TOTAL_VIDEO_VIEWS` | | Video Duration - Total | The length of your published videos | Organic + Promoted | `VIDEO_DURATION` | | Engagement Rate (Views) - Total | The percentage of people who engaged with your posts after seeing them | Organic + Promoted | `VIEWS_BASED_ENGAGEMENT_RATE` | | Metric Name | Description | Post Types | Metric API Name | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----------------------------------- | | Amount Spent - Paid | The total amount of money you've spent boosting your posts. Due to API delays, recent spend figures may be estimated for up to 48 hours. | Promoted | `AMOUNT_SPENT` | | Comments - Organic | The number of comments your posts received | Organic | `COMMENTS` | | Cost per ThruPlay - Paid | The average cost per Thruplay for your videos | Promoted | `COST_PER_THRUPLAY` | | CPC - Paid | The average cost per click on your promoted posts | Promoted | `CPC` | | CPM - Paid | The average cost per 1,000 impressions on your promoted posts | Promoted | `CPM` | | CTR - Paid | The percentage of times people clicked your promoted posts after seeing them | Promoted | `CTR` | | Effectiveness - Total | The percentage of viewers who saw your posts and engaged with them | Organic + Promoted | `EFFECTIVENESS_V2` | | Engagement Rate - Total | The percentage of people who engaged with your posts after seeing them | Organic + Promoted | `ENGAGEMENT_RATE_V2` | | Frequency - Paid | The average number of times people saw your promoted posts | Promoted | `FREQUENCY` | | Link Clicks - Total | The number of times people clicked on the link in a post or link preview for posts published during the Reporting Period | Organic + Promoted | `LINK_CLICKS` | | Effectiveness - Organic | The percentage of viewers who saw your posts and engaged with them. Organic Effectiveness is not available for Promoted posts published after June 15, 2026 | Organic | `ORGANIC_EFFECTIVENESS_V2` | | Engagements - Organic | The total number of engagements your posts received | Organic | `ORGANIC_ENGAGEMENTS_V2` | | Engagement Rate - Organic | The percentage of people who engaged with your posts after seeing them | Organic | `ORGANIC_ENGAGEMENT_RATE_V2` | | Reactions - Organic | The total number of reactions your posts published during the reporting period received | Organic | `ORGANIC_REACTIONS` | | Shares - Organic | The number of times your posts published during the reporting period were shared | Organic | `ORGANIC_SHARES` | | Video Complete Views - Organic | The number of times your videos were played from the beginning to 95%, or more, of their length | Organic | `ORGANIC_VIDEO_COMPLETE_VIEWS` | | Video Views - Organic | The number of times your videos were viewed | Organic | `ORGANIC_VIDEO_VIEWS` | | Views - Organic | The number of times your posts were viewed | Organic | `ORGANIC_VIEWS` | | Other Clicks - Total | The number of clicks on your posts, including links and other clickable elements on posts published during the reporting period | Organic + Promoted | `OTHER_CLICKS` | | Comments - Total | The number of comments your posts received | Organic + Promoted | `PAID_AND_ORGANIC_COMMENTS` | | Comments - Paid | The number of comments your posts received | Promoted | `PAID_COMMENTS` | | Effectiveness - Paid | The percentage of viewers who saw your posts and engaged with them | Promoted | `PAID_EFFECTIVENESS_V2` | | Engagements - Paid | The total number of engagements your posts received | Promoted | `PAID_ENGAGEMENTS` | | Engagement Rate - Paid | The percentage of people who engaged with your posts after seeing them | Promoted | `PAID_ENGAGEMENT_RATE_V2` | | Reach - Paid | The number of unique accounts that have viewed your posts at least once. Note: This metric uses Reach from Ad campaigns. | Promoted | `PAID_REACH_V2` | | Reactions - Paid | The number of reactions your posts received. Reactions include Like, Love, Care, Haha, Wow, Sad, and Angry. | Promoted | `PAID_REACTIONS` | | Shares - Paid | The number of times your posts were shared | Promoted | `PAID_SHARES` | | Video Complete Views - Paid | The number of times your videos were played from the beginning to 95% or more of their length | Promoted | `PAID_VIDEO_COMPLETE_VIEWS` | | Video Views - Paid | The number of times your videos were viewed | Promoted | `PAID_VIDEO_VIEWS` | | Views - Paid | The number of times your posts were viewed | Promoted | `PAID_VIEWS` | | Photo View Clicks - Total | The number of times users clicked on your photos published during the reporting period | Organic + Promoted | `PHOTO_VIEW_CLICKS` | | Post Clicks - Total | The number of times a user clicked anywhere on your posts published during the reporting period | Organic + Promoted | `POST_CLICKS` | | Reactions - Total | The number of times people clicked on like, care, love, wow, haha, sad, and anger reactions on posts published during the Reporting Period | Organic + Promoted | `REACTIONS` | | Plays - Total | The number of times your videos published during the Reporting Period were initially played. This excludes replays | Organic + Promoted | `REELS_BLUE_REELS_PLAYS_COUNT` | | Replays - Total | The number of rewatches your videos published during the Reporting Period received in the same session | Organic + Promoted | `REELS_FB_REELS_REPLAY_COUNT` | | Avg. Time Watched - Total | The average time your videos published during the Reporting Period were played during a single viewing | Organic + Promoted | `REELS_POST_VIDEO_AVG_TIME_WATCHED` | | Follows - Total | The number of viewers who followed your Page after viewing your videos published during the Reporting Period | Organic + Promoted | `REELS_POST_VIDEO_FOLLOWERS` | | Total Time Watched - Total | The sum of time that viewers watched your videos published during the Reporting Period | Organic + Promoted | `REELS_POST_VIDEO_VIEW_TIME` | | Reactions - Angry - Total | The number of times people used an Angry reaction to your post | Organic + Promoted | `REELS_REACTION_ANGRY` | | Reactions - Haha - Total | The number of times people used a Haha reaction to your post | Organic + Promoted | `REELS_REACTION_HAHA` | | Reactions - Like - Total | The number of times people used a Like or a Care reaction to your post | Organic + Promoted | `REELS_REACTION_LIKE` | | Reactions - Love - Total | The number of times people used a Love reaction to your post | Organic + Promoted | `REELS_REACTION_LOVE` | | Reactions - Sad - Total | The number of times people used a Sad reaction to your post | Organic + Promoted | `REELS_REACTION_SAD` | | Reactions - Wow - Total | The number of times people used a Wow reaction to your post | Organic + Promoted | `REELS_REACTION_WOW` | | Shares - Total | The number of times your posts were shared | Organic + Promoted | `SHARES` | | ThruPlays - Paid | The number of times your posts were watched to completion or for at least 15 seconds | Promoted | `THRUPLAYS` | | Engagements - Total | The total number of engagements your posts received | Organic + Promoted | `TOTAL_ENGAGEMENTS_V2` | | Viewers - Total | The number of unique accounts that saw your posts at least once. Note: Values before July 31, 2025 reflect Reach, which Meta replaced with Viewers. | Organic + Promoted | `TOTAL_REACH` | | Video Complete Views - Total | The number of times your videos published during the Reporting Period were played from the beginning to 95%, or more, of its length | Organic + Promoted | `VIDEO_COMPLETE_VIEWS` | | Video Plays 25% - Paid | The number of times your video was played to 25% of its length, including plays that skipped to this point | Promoted | `VIDEO_PLAYS_25` | | Video Plays 50% - Paid | The number of times your video was played to 50% of its length, including plays that skipped to this point | Promoted | `VIDEO_PLAYS_50` | | Video Plays 75% - Paid | The number of times your video was played to 75% of its length, including plays that skipped to this point | Promoted | `VIDEO_PLAYS_75` | | Video Views - Total | The number of times your videos were viewed | Organic + Promoted | `VIDEO_VIEWS` | | Views - Total | The number of times your posts were viewed | Organic + Promoted | `VIEWS` | | Metric Name | Description | Post Types | Metric API Name | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------- | | Avg. Watch Time | The average time spent watching your video Pins | Organic | `AVG_WATCH_TIME` | | Pin Clicks | The number of times your Pins were clicked to view more details during the Reporting Period | Organic | `CLOSEUPS` | | Engagements | The total number of engagements your Pins received | Organic | `ENGAGEMENTS` | | Engagement Rate | The percentage of people who engaged with your posts after seeing them | Organic | `ENGAGEMENT_RATE` | | Impressions | The number of times your Pins were viewed or displayed | Organic | `IMPRESSIONS` | | Outbound Clicks | The number of times the links in your Pins were clicked during the Reporting Period | Organic | `LINK_CLICKS` | | Saves | The number of times users saved your Pins during the reporting period | Organic | `SAVES` | | Video Views | The number of views lasting at least two seconds with 50% of the video pin visible from post published during the reporting period | Organic | `TOTAL_VIDEO_VIEWS` | | Metric Name | Description | Post Types | Metric API Name | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----------------------------------- | | Avg. View Duration - Total | The average amount of time viewers spent watching your organic and promoted videos published during the Reporting Period | Organic + Promoted | `TOTAL_AVG_VIEW_DURATION` | | Avg. Percentage Viewed - Total | The average retention rate of your organic and promoted videos published during the Reporting Period | Organic + Promoted | `TOTAL_AVG_VIEW_PERCENTAGE` | | Card Clicks - Total | The number of times the cards were clicked on your organic and promoted videos published during the Reporting Period | Organic + Promoted | `TOTAL_CARD_CLICKS` | | Card Click Rate - Total | The click through rate for all cards on your videos | Organic + Promoted | `TOTAL_CARD_CLICK_RATE` | | Card Impressions - Total | The number of times cards were displayed on your organic and promoted videos published during the Reporting Period | Organic + Promoted | `TOTAL_CARD_IMPRESSIONS` | | Card Teaser Clicks - Total | The number of times the card teasers were clicked on your organic and promoted videos published during the Reporting Period | Organic + Promoted | `TOTAL_CARD_TEASER_CLICKS` | | Card Teaser Click Rate - Total | The percentage of people who clicked on a card teaser after seeing it | Organic + Promoted | `TOTAL_CARD_TEASER_CLICK_RATE` | | Card Teaser Impressions - Total | The number of times card teasers were displayed on your organic and promoted videos published during the Reporting Period | Organic + Promoted | `TOTAL_CARD_TEASER_IMPRESSIONS` | | Comments - Total | The total number of comments your organic and promoted videos published during the Reporting Period received | Organic + Promoted | `TOTAL_COMMENTS` | | Dislikes - Total | The total number of dislikes your organic and promoted videos published during the Reporting Period received | Organic + Promoted | `TOTAL_DISLIKES` | | Engagements - Total | The total number of engagements your organic and promoted videos published during the Reporting Period received. Total Engagements = Likes + Dislikes + Comments + Shares | Organic + Promoted | `TOTAL_ENGAGEMENTS` | | Watch Time - Total | The total amount of time that viewers watched organic and promoted videos on your channel that were published during the Reporting Period | Organic + Promoted | `TOTAL_ESTIMATED_SECONDS_WATCHED` | | Premium Watch Time - Total | The total amount of time your organic and promoted videos published during the Reporting Period were viewed by YouTube Premium members | Organic + Promoted | `TOTAL_EST_PREMIUM_SECONDS_WATCHED` | | Likes - Total | The total number of likes your organic and promoted videos published during the Reporting Period received | Organic + Promoted | `TOTAL_LIKES` | | Premium Views - Total | The number of times your organic and promoted videos published during the Reporting Period were viewed by YouTube Premium members | Organic + Promoted | `TOTAL_PREMIUM_VIEWS` | | Shares - Total | The total number of shares your organic and promoted videos published during the Reporting Period received | Organic + Promoted | `TOTAL_SHARES` | | Subscribers - Gained | The number of viewers who subscribed while watching your videos | Organic + Promoted | `TOTAL_SUBSCRIBERS_GAINED` | | Subscribers - Lost | The number of viewers who unsubscribed while watching your videos | Organic + Promoted | `TOTAL_SUBSCRIBERS_LOST` | | Added to Playlist - Total | The total number of times your organic and promoted videos published during the Reporting Period were added to a playlist | Organic + Promoted | `TOTAL_VIDEOS_ADDED_TO_PLAYLIST` | | Video Views - Total | The total number of times your organic and promoted videos published during the Reporting Period were viewed | Organic + Promoted | `TOTAL_VIDEO_VIEWS` | | Metric Name | Description | Post Types | Metric API Name | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------- | | Clicks | The number of times people clicked on your posts | Organic | `CLICKS` | | CTR | The percentage of people that clicked on your posts after seeing them | Organic | `CLICK_THROUGH_RATE_BY_POST` | | Comments | The number of comments your posts received | Organic | `COMMENTS` | | Engagements | The total number of engagements on your posts published during the reporting period Engagements = Clicks + Reactions + Comments + Reposts | Organic | `ENGAGEMENTS_BY_POST` | | Engagement Rate | The percentage of people who engaged with your posts after seeing them | Organic | `ENGAGEMENT_RATE` | | Impressions | The number of times your posts were viewed or displayed | Organic | `IMPRESSIONS` | | Reactions | The number of reactions your posts received | Organic | `REACTIONS` | | Shares | The number of times your posts were shared | Organic | `SHARES` | | Unique Impressions | The number of unique LinkedIn members that saw your posts. Similar to Reach. | Organic | `UNIQUE_IMPRESSIONS` | | Video Views | The number of times your videos were viewed | Organic | `VIDEO_VIEWS` | | Watch Time | The total amount of time viewers spent watching your videos | Organic | `WATCH_TIME` | | Metric Name | Description | Post Types | Metric API Name | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ------------------- | | Engagement Rate | The percentage of people who engaged with your posts after seeing them | Organic | `ENGAGEMENT_RATE` | | Impressions | The number of times your posts were viewed or displayed | Organic | `IMPRESSIONS` | | Likes | The number of likes your Tweets received during the reporting period | Organic | `LIKES` | | Link Clicks | The number of times links on your Tweets were clicked during the reporting period | Organic | `LINK_CLICKS` | | Profile Clicks | The number of times your profile has been clicked from Tweets during the reporting period | Organic | `PROFILE_CLICKS` | | Quote Posts | The number of times your Tweets were Quote Tweeted during the reporting period | Organic | `QUOTE_TWEETS` | | Replies | The number of replies your Tweets received during the reporting period | Organic | `REPLIES` | | Reposts | The number of times your Tweets were Retweeted during the reporting period | Organic | `RETWEETS` | | Engagements | The total number of times a user interacted with your tweets during the reporting period, including Retweets, replies, likes, hashtags, or link clicks | Organic | `TOTAL_ENGAGEMENTS` | | Total Reposts | The total number of times your Tweets were Retweeted during the reporting period. Total Retweets = Retweets + Quote Tweets | Organic | `TOTAL_RETWEETS` | | Video Views | The number of times your organic videos were viewed during the reporting period | Organic | `VIDEO_VIEWS` | ## Next steps You now have a ranked list of posts with engagement metrics, media URLs, and permalinks. Use this data to: * **Build performance dashboards** - Display top posts with thumbnails and engagement metrics in BI tools * **Track trends** - Pull weekly Content reports to see which posts consistently perform best * **Inform creative strategy** - Analyze top posts to identify patterns in format, topic, or posting time **Related guides:** * [Pull Total Social Metrics Across Channels →](/guides/pull-total-social-metrics) * [Visualize Time-Series Metrics with Graph Report →](/guides/pull-time-series-data-with-graph-report) * [Track Campaign Performance with Content Tags →](/guides/track-analytics-with-content-tag-api) * [View the Full API Reference →](https://developers.dashsocial.com/reference/get_reports-data) # Owned report overview Source: https://developer.dashsocial.com/guides/reporting/export-dashboard-report-data-via-api/owned-report/overview Track content you published across your connected social channels to measure campaign performance. Tracks content you published across your connected social channels to measure campaign performance and content strategy effectiveness. **Available report types:** Pull Total Social Metrics Across Channels Pull Time-Series Data with Graph Report Get Top-Performing Posts with Content Report # Pull time-series data with graph report Source: https://developer.dashsocial.com/guides/reporting/export-dashboard-report-data-via-api/owned-report/pull-time-series-data-with-graph-report Track owned social metrics over time using daily or monthly time-series data for trend visualization. Track how your social metrics change over time. This guide shows you how to pull daily or monthly time-series data using the Graph report. Use this data to chart trends in Power BI, Tableau, or Looker. *** ## Use cases Static snapshots miss the story. The Graph report breaks metrics down by date so you can track momentum and spot patterns over time. Chart daily Instagram Reels views to identify which days drive the most engagement Plot monthly impressions across brands to see which campaigns gained traction Track TikTok engagement trends over 90 days to quantify campaign impact *** ## Before you start Make sure you have: * **API Key** - Your authentication token * **Brand ID** - The ID for the brand you want to report on If you need help getting these, check out our [API Quickstart](https://developer.dashsocial.com/guides/get-started/quickstart). ### Test in the dashboard first Build a Graph report in the Dash Social Dashboard UI to preview channel, brand, and metric combinations before using the API. *** ## Implementation ### Step 1: Map your parameters Understand what parameters are available to control your time-series data.
Parameter Description
`brand_ids` Your brand ID. Use comma-separated values for multiple brands (e.g., `144,256`).
`channels` Social platform to report on. Options: * `INSTAGRAM` - Feed posts * `INSTAGRAM_STORIES` - Stories * `FACEBOOK` - Facebook posts * `TIKTOK` - TikTok videos * `TWITTER` - X posts * `YOUTUBE` - YouTube videos * `PINTEREST` - Pinterest pins * `LINKEDIN` - LinkedIn posts
`metrics` Time-series metrics to track. See the Metrics section below for all available options. Track multiple metrics by separating with commas (e.g., `VIEWS,REACH,TOTAL_ENGAGEMENTS`).
`report_type` Set to `GRAPH` to return time-series values grouped by date rather than aggregated totals.
`time_scale` Time granularity for your data: * `DAILY` (default) - Breakdown by day * `MONTHLY` - Breakdown by month
`start_date` / `end_date` Your reporting period in `YYYY-MM-DD` format.
`context_start_date` / `context_end_date` Optional comparison period for trend analysis in `YYYY-MM-DD` format. Compare current performance against a previous time range.
**Time-series data structure:** The Graph report returns values grouped by date. Each date in your range has its own metric value for plotting trends over time. *** ### Step 2: Make the API call Send a GET request to `/reports/data` using the parameters from Step 1. Set `report_type=GRAPH` to get time-series data broken down by date instead of aggregated totals. ```http theme={null} GET https://dashboard.dashsocial.com/reports/data?channels=INSTAGRAM&brand_ids=144&start_date=2025-05-01&end_date=2025-05-07&metrics=VIEWS&report_type=GRAPH&time_scale=DAILY ``` This example pulls daily Instagram views for 7 days. Swap in different parameters from Step 1 to customize your analysis. *** ### Step 3: Read the response The API returns time-series data organized by brand, channel, metric, and date. Sample response: ```json theme={null} { "data": { "144": { "avatar": "https://cdn.dashhudson.com/avatars/2306810931.jpeg", "data_type": "BRAND", "name": "sunny.today", "permissions": { "brand": { "can_access_metric": true }, "user": { "can_access_brand": true } }, "user_has_access": true }, "metrics": { "VIEWS": { "ALL_CHANNELS": { "2025-05-01": 205.0, "2025-05-02": null, "2025-05-03": null, "2025-05-04": 13.0, "2025-05-05": 11.0, "2025-05-06": 11.0, "2025-05-07": 51.0 } } } }, "product_category": "OWNED" } ``` Response structure: * **`data`**: Nested structure organized by brand → channel → metric → date * **Brand ID** (e.g., `144`): Your brand ID * **Channel** (e.g., `INSTAGRAM`): The social platform * **Metric** (e.g., `VIEWS`): The performance metric * **Date** (e.g., `2025-05-01`): Each date in your range * **Value** (e.g., `205.0`): The metric value for that date In this example, Instagram views ranged from 130 to 210 during May 1-7, 2025. Peak performance occurred on May 6. **Want aggregated totals instead?** Use the [Metric report](/guides/aggregate-cross-channel-metrics) to get summed KPIs without time breakdowns. *** ### Querying multiple brands and channels When you query multiple brands across multiple channels, add `aggregate_by=BRAND` and `secondary_aggregate_by=CHANNEL` to control how the response is grouped. Without these parameters, the grouping depends on the report type and request context, which may not match what you expect. ```http theme={null} GET https://dashboard.dashsocial.com/reports/data ?channels=INSTAGRAM,FACEBOOK &brand_ids=144,4688 &start_date=2026-05-01 &end_date=2026-05-07 &metrics=TOTAL_ENGAGEMENTS,TOTAL_FOLLOWERS &report_type=GRAPH &aggregate_by=BRAND &secondary_aggregate_by=CHANNEL ``` The response nests channel data under a `breakdowns` key inside each brand, with time-series values for each date: ```json theme={null} { "data": { "144": { "avatar": "https://cdn.dashhudson.com/avatars/2306810931.jpeg", "breakdowns": { "FACEBOOK": { "data_type": "CHANNEL", "metrics": { "TOTAL_ENGAGEMENTS": { "FACEBOOK": { "2026-05-01": null, "2026-05-02": null, "2026-05-03": null, "2026-05-04": 2.0, "2026-05-05": 0, "2026-05-06": 1.0, "2026-05-07": 0 } }, "TOTAL_FOLLOWERS": { "FACEBOOK": { "2026-05-01": 150.0, "2026-05-02": 150.0, "2026-05-03": 150.0, "2026-05-04": 150.0, "2026-05-05": 152.0, "2026-05-06": 152.0, "2026-05-07": 152.0 } } } }, "INSTAGRAM": { "data_type": "CHANNEL", "metrics": { "TOTAL_ENGAGEMENTS": { "INSTAGRAM": { "2026-05-01": 1.0, "2026-05-02": null, "2026-05-03": 2.0, "2026-05-04": null, "2026-05-05": 1.0, "2026-05-06": null, "2026-05-07": null } }, "TOTAL_FOLLOWERS": { "INSTAGRAM": { "2026-05-01": 230.0, "2026-05-02": 230.0, "2026-05-03": 229.0, "2026-05-04": 229.0, "2026-05-05": 229.0, "2026-05-06": 229.0, "2026-05-07": 229.0 } } } } }, "data_type": "BRAND", "name": "sunny.today", "permissions": { "brand": { "can_access_metric": true }, "user": { "can_access_brand": true } }, "user_has_access": true }, "metrics": { "TOTAL_ENGAGEMENTS": { "ALL_CHANNELS": { "2026-05-01": 1.0, "2026-05-02": null, "2026-05-03": 2.0, "2026-05-04": 2.0, "2026-05-05": 1.0, "2026-05-06": 1.0, "2026-05-07": 0 } } } }, "product_category": "OWNED" } ``` Read metrics from each entry using the path `data..breakdowns..metrics...`. The top-level `metrics` object contains totals across all brands and channels for each date. *** ## Metrics **Some metrics require a connected Ads account.** If a request returns `no_ad_account_matching_report_channels`, one or more of the requested metrics depends on Ads data that the brand has not connected. On Facebook and TikTok, metrics labelled "Organic only" or "Promoted only" require a connected Ads account. Combined "Total (Organic + Promoted)" metrics and account-level metrics do not. On Instagram, metrics representing "Total (Organic + Promoted)" performance require a connected Meta Ads account. | Metric Name | Description | Post Types | Metric API Name | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------------------------------------------ | | Accounts Engaged | The number of accounts that have interacted with your organic and promoted posts during the reporting period | | `ACCOUNTS_ENGAGED` | | Accounts Reached | The number of unique accounts that have seen your content. Estimated by Instagram. This total may not equal the sum of follower and non-follower reach due to differences in how Instagram samples and estimates the metric. Note: Instagram account-level metrics include Instagram Stories stats. | | `ACCOUNTS_REACHED` | | Accounts Reached (Followers) | The number of unique follower accounts that have seen your content. Estimated by Instagram. Note: Instagram account-level metrics include Instagram Stories stats. | | `ACCOUNTS_REACHED_FOLLOWERS` | | Accounts Reached (Non-Followers) | The number of unique non-follower accounts that have seen your content. Estimated by Instagram. Note: Instagram account-level metrics include Instagram Stories stats. | | `ACCOUNTS_REACHED_NON_FOLLOWERS` | | Ad Engagements - Paid | The total number of ad engagements your promoted posts received | Promoted | `AD_ENGAGEMENTS` | | Avg. Time Watched - Organic | The average time your videos were played during a single viewing | Organic | `AVG_AVG_WATCH_TIME` | | Avg. Effectiveness - Organic | The average percentage of users that saw your posts and engaged with them Avg. Effectiveness = Engagements / Reach | Organic | `AVG_EFFECTIVENESS_ENGAGEMENTS` | | Avg. Engagement Rate (Followers) - Organic | The average percentage of your audience that engaged with your posts published during the Reporting Period. Engagement Rate = Organic Engagements / Followers | Organic | `AVG_ENGAGEMENT_RATE` | | Avg. Engagement Rate (Views) - Organic | The average percentage of your audience that engaged with your posts published during the Reporting Period. Engagement Rate = Organic Engagements / Views | Organic | `AVG_ENGAGEMENT_RATE_VIEWS` | | Avg. Entertainment Score - Organic | The average Entertainment Score of your Reels published during the reporting period. The score is on a scale of 0 to 10 and is based on volume of organic engagements compared to reach. | Organic | `AVG_ENTERTAINMENT_SCORE` | | Avg. Reach - Total | The average number of unique accounts that saw your posts | Organic + Promoted | `AVG_PAID_AND_ORGANIC_REACH` | | Engagement Rate (Impressions) - Paid | The promoted engagement rate on your posts this period | Promoted | `AVG_PAID_ENGAGEMENT_RATE` | | Avg. Reach - Paid | The average number of unique accounts that saw your posts | Promoted | `AVG_PAID_REACH` | | Avg. Reach - Organic | The average number of unique accounts that saw your posts published during the Reporting Period | Organic | `AVG_REACH` | | Avg. Skip Rate - Organic | The average percentage of viewers who skipped your Reels within the first 3 seconds | Organic | `AVG_REELS_SKIP_RATE` | | Book Now Clicks - All Posts | The number of times people tapped the Book Now button on your profile after viewing your posts | | `BOOK_NOW_CLICKS` | | Call Clicks - All Posts | The number of times people tapped the call button on your profile after viewing your posts | | `CALL_CLICKS` | | Clicks - Paid | The total number of clicks on your promoted posts. This can include link clicks, clicks to your profile, and more. | Promoted | `CLICKS` | | Comments - Total - All Posts | The number of comments your posts received. Note: Instagram account-level metrics include Instagram Stories stats. | Organic + Promoted | `COMMENTS_ACCOUNT_STATS` | | Post Sentiment - Negative | The percentage of posts published during the reporting period with an overall negative comment sentiment | Organic + Promoted | `COMMENT_SENTIMENT_NEGATIVE_RATE` | | Post Sentiment - Negative | The percentage of posts with a negative overall comment sentiment | Organic | `COMMENT_SENTIMENT_NEGATIVE_RATE_ORGANIC` | | Post Sentiment - Negative | The percentage of posts with a negative overall comment sentiment | Promoted | `COMMENT_SENTIMENT_NEGATIVE_RATE_PROMOTED` | | Post Sentiment - Neutral | The percentage of posts published during the reporting period with an overall neutral comment sentiment | Organic + Promoted | `COMMENT_SENTIMENT_NEUTRAL_RATE` | | Post Sentiment - Neutral | The percentage of posts with a neutral overall comment sentiment | Organic | `COMMENT_SENTIMENT_NEUTRAL_RATE_ORGANIC` | | Post Sentiment - Neutral | The percentage of posts with a neutral overall comment sentiment | Promoted | `COMMENT_SENTIMENT_NEUTRAL_RATE_PROMOTED` | | Post Sentiment - Positive | The percentage of posts published during the reporting period with an overall positive comment sentiment | Organic + Promoted | `COMMENT_SENTIMENT_POSITIVE_RATE` | | Post Sentiment - Positive | The percentage of posts with a positive overall comment sentiment | Organic | `COMMENT_SENTIMENT_POSITIVE_RATE_ORGANIC` | | Post Sentiment - Positive | The percentage of posts with a positive overall comment sentiment | Promoted | `COMMENT_SENTIMENT_POSITIVE_RATE_PROMOTED` | | Content Engagements - All Posts | The number of likes, comments, shares, and saves your content received during the reporting period. Note: Instagram account-level metrics include Instagram Stories stats. | | `CONTENT_ENGAGEMENTS` | | Engagement Rate (Views) - All Posts | The percentage of people who engaged with your content after viewing it | | `CONTENT_ENGAGEMENT_RATE_VIEWS` | | Views - Crossposted - Organic | Total views across Instagram and Facebook for content crossposted natively between platforms. For Reels, includes views from crossposting or cross-app recommendations, where Reels appear on Facebook under your Instagram username. | Organic | `CROSSPOSTED_VIEWS` | | Views - Facebook - Organic | The number of views your posts received on Facebook, for content crossposted natively from Instagram. For Reels, also includes views from cross-app recommendations, where Reels appear on Facebook under your Instagram username. | Organic | `FACEBOOK_VIEWS` | | Followers - Lost | The total numbers of users who unfollowed your account during the Reporting Period. \*Lost Followers data is received once per day in the Pacific Timezone. | | `FOLLOWERS_LOST` | | Followers - Growth Rate | The percentage your followers increased by during the Reporting Period. Follower Growth Rate = (New Followers - Old Followers) / Old Followers x 100% | | `FOLLOWER_GROWTH_RATE` | | Follows - Organic | The number of accounts that started following you after viewing your post | Organic | `FOLLOWS` | | LikeShop Clicks - All Posts | The total number of clicks on any LikeShop feed products during the reporting period | | `LIKESHOP_CLICKS` | | LikeShop Clicks | The number of clicks on your LikeShop feed products on posts published during the reporting period | | `LIKESHOP_CLICKS_BY_POST` | | LikeShop Contact Submissions - All Posts | The number of email submissions during the reporting period | | `LIKESHOP_CONTACT_SUBMISSIONS` | | LikeShop CTR - All Posts | The percentage of times people clicked your product links after viewing your post | | `LIKESHOP_CTR` | | LikeShop Posts | The number of posts you've published during the reporting period that include product links. These are the posts visible on your LikeShop. | | `LIKESHOP_POSTS` | | LikeShop Views - All Posts | The number of times your posts were displayed on a person's screen. This includes repeat views. | | `LIKESHOP_VIEWS` | | Likes - Total - All Posts | The number of likes your posts received. Note: Instagram account-level metrics include Instagram Stories stats. | Organic + Promoted | `LIKES_ACCOUNT_STATS` | | Followers - Net New | The net new number of people who have followed your account | | `NET_NEW_FOLLOWERS` | | Number of Posts | The number of posts you've published during the reporting period | Organic + Promoted | `NUMBER_OF_POSTS` | | Number of Posts | The number of posts you've published during the reporting period | Organic | `NUMBER_OF_POSTS_ORGANIC` | | Number of Posts | The number of posts you've published during the reporting period | Promoted | `NUMBER_OF_POSTS_PAID` | | Follower Activity - All Posts | The average times your followers were active during the reporting period. Data from the Instagram API may be delayed by up to 3 days. | | `ONLINE_FOLLOWERS` | | Comments - Organic | The number of comments on your posts published during the reporting period | Organic | `ORGANIC_COMMENTS` | | Likes - Organic | The number of likes received on posts published during the reporting period | Organic | `ORGANIC_LIKES` | | Comments - Paid | The number of comments your posts received | Promoted | `PAID_COMMENTS` | | Cost per ThruPlay - Paid | The average cost per Thruplay for your videos | Promoted | `PAID_COST_PER_THRUPLAY` | | Impressions - Paid | The number of times your posts were viewed or displayed | Promoted | `PAID_IMPRESSIONS` | | Likes - Paid | The number of likes your posts received | Promoted | `PAID_LIKES` | | Saves - Paid | The number of times your posts were saved | Promoted | `PAID_SAVES` | | Shares - Paid | The number of times your promoted posts were shared | Promoted | `PAID_SHARES_BY_POST` | | Engagements - Paid | The total number of engagements your promoted posts received | Promoted | `PAID_TOTAL_ENGAGEMENTS` | | Video Views - Paid | The number of times your videos were viewed | Promoted | `PAID_VIDEO_VIEWS` | | Profile Clicks - Organic | The number of actions people take when they visit your profile after viewing your post. This can include bio link clicks, calls, emails, and more. | Organic | `PROFILE_CLICKS` | | Profile Bio Link Clicks | The number of times people clicked the link in your profile bio after viewing your post | Organic | `PROFILE_CLICKS_BIO` | | Profile Call Clicks - Organic | The number of times people tapped the call button on your profile after viewing your posts | Organic | `PROFILE_CLICKS_CALL` | | Profile Directions Clicks - Organic | The number of times people clicked to get directions from your profile after viewing your posts | Organic | `PROFILE_CLICKS_DIRECTIONS` | | Profile Email Clicks | The number of times people tapped the email button on your profile after viewing your posts | Organic | `PROFILE_CLICKS_EMAIL` | | Profile Other Clicks - Organic | The number of times people clicked other profile buttons after viewing your posts | Organic | `PROFILE_CLICKS_OTHER` | | Profile Text Clicks | The number of times people tapped the text message button on your profile after viewing your posts | Organic | `PROFILE_CLICKS_TEXT` | | Profile Views | The amount of times your profile has been viewed during the Reporting Period | | `PROFILE_VIEWS` | | Profile Visits - Organic | The number of times your profile was visited after viewing your post | Organic | `PROFILE_VISITS` | | Reposts - Organic | The number of times your posts have been reposted | Organic | `REPOSTS` | | Reposts - Organic - All Posts | The number of times your posts have been reposted, minus any un-reposts. This metric can be negative if un-reposts exceed reposts. Note: Instagram account-level metrics include Instagram Stories stats. | Organic | `REPOSTS_ACCOUNT_STATS` | | Saves - Organic | The number of times your posts published during the reporting period were saved | Organic | `SAVES` | | Saves - Total - All Posts | The number of times your posts were saved. Note: Instagram account-level metrics include Instagram Stories stats. | Organic + Promoted | `SAVES_ACCOUNT_STATS` | | Shares - Organic | The number of times your posts published were shared during the reporting period | Organic | `SHARES` | | Shares - Total - All Posts | The number of times your posts were shared. Note: Instagram account-level metrics include Instagram Stories stats. | Organic + Promoted | `SHARES_ACCOUNT_STATS` | | Engagements - Total | The total number of engagements from all posts published during the Reporting Period | Organic + Promoted | `SUM_TOTAL_ENGAGEMENTS` | | ThruPlays - Paid | The number of times your videos were watched to completion or for at least 15 seconds | Promoted | `THRUPLAYS` | | Comments - Total | The number of comments your posts received | Organic + Promoted | `TOTAL_COMMENTS` | | Engagements - Organic | The total number of engagements on your posts published during the reporting period Engagements = (Likes + Saves + Comments + Shares) - (Unlikes + Unsaves + Deleted comments) | Organic | `TOTAL_ENGAGEMENTS` | | Followers | The total number of followers you have on this channel | | `TOTAL_FOLLOWERS` | | Likes - Total | The number of likes your posts received | Organic + Promoted | `TOTAL_LIKES` | | Saves - Total | The number of times your posts were saved | Organic + Promoted | `TOTAL_SAVES` | | Shares - Total | The number of times your posts were shared | Organic + Promoted | `TOTAL_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` | | Video Plays 100% - Paid | The number of times your videos were played to 100% of their length, including plays that skipped to this point | Promoted | `VIDEO_PLAYS_100` | | Video Plays 25% - Paid | The number of times your videos were played to 25% of their length, including plays that skipped to this point | Promoted | `VIDEO_PLAYS_25` | | Video Plays 50% - Paid | The number of times your videos were played to 50% of their length, including plays that skipped to this point | Promoted | `VIDEO_PLAYS_50` | | Video Plays 75% - Paid | The number of times your videos were played to 75% of their length, including plays that skipped to this point | Promoted | `VIDEO_PLAYS_75` | | Views - Organic | The number of times your posts were displayed on a person's screen. This includes repeat views. | Organic | `VIEWS` | | Views - All Posts | The number of times your posts were viewed or displayed. The sum of follower and non-follower views may not add to the Total due to differences in how Instagram samples and estimates the metric. Note: Instagram account-level metrics include Instagram Stories stats. | | `VIEWS_ALL_ACCOUNT_STATS` | | Views (Followers) - All Posts | The number of times your posts were viewed by your followers during the reporting period. The sum of follower and non-follower views may not add to the Total due to differences in how Instagram samples and estimates the metric. Note: Instagram account-level metrics include Instagram Stories stats. | | `VIEWS_FOLLOWERS_ACCOUNT_STATS` | | Views (Non-Followers) - All Posts | The number of times your posts were viewed by non-followers during the reporting period. The sum of follower and non-follower views may not add to the Total due to differences in how Instagram samples and estimates the metric. Note: Instagram account-level metrics include Instagram Stories stats. | | `VIEWS_NON_FOLLOWERS_ACCOUNT_STATS` | | Total Time Watched - Organic | The sum of the time that all viewers watched your videos for | Organic | `WATCH_TIME` | | Metric Name | Description | Post Types | Metric API Name | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | --------------------------- | | Avg. Completion Rate | The average percentage of people who viewed the entire story. Completion Rate = (Exits - Views) / Views. This metric is only available for reporting after March 24, 2025. | Organic | `AVG_COMPLETION_RATE_VIEWS` | | Avg. Exit Rate | The percentage of people who exited out of the story. Exit Rate = Exits / Views. This metric is only available for reporting after March 24, 2025. | Organic | `AVG_EXIT_RATE_VIEWS` | | Avg. Reach | The average number of unique accounts that saw your stories published during the Reporting Period. | Organic | `AVG_REACH` | | Exits | The number of times that a user has swiped out of the story or tapped the X in the upper-right corner of the story frame published during the reporting period. An exit is counted even if it occurred in the last millisecond. | Organic | `EXITS` | | Number of Story Frames | The number of posts you've published during the reporting period | Organic | `NUMBER_OF_POSTS` | | Replies | The number of times people replied to your Instagram Stories published during the reporting period. Due to API restrictions, replies from accounts in the European Economic Area (EEA) or Japan are not included. For Stories created in the EEA or Japan, replies return a value of 0. | Organic | `REPLIES` | | Replies - All Posts | The number of replies your story frames received | Organic + Promoted | `STORY_REPLIES` | | Stories Link Clicks | The number of link clicks on the story frames published during during the reporting period. Only links scheduled through Dash are trackable via the platform. | Organic | `SWIPE_UPS` | | Taps Back | The number of people who tapped backwards on your stories published during the reporting period | Organic | `TAPS_BACK` | | Taps Forward | The number of people who tapped forward on your stories published during the reporting period | Organic | `TAPS_FORWARD` | | 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` | | Views | The number of times your story frames published during the reporting period was displayed on a person's screen. This includes repeat views This metric is only available for reporting after March 24, 2025. | Organic | `VIEWS` | | Metric Name | Description | Post Types | Metric API Name | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------------------------------------------ | | Avg. Effectiveness - Total | The average percentage of viewers who saw your posts and engaged with them | Organic + Promoted | `AVG_EFFECTIVENESS_V2` | | Avg. Engagement Rate - Total | The average percentage of people who engaged with a post after seeing it | Organic + Promoted | `AVG_ENGAGEMENT_RATE_V2` | | Avg. Effectiveness - Organic | The average percentage of viewers who saw your posts and engaged with them. Organic Effectiveness is not available for Promoted posts published after June 15, 2026 | Organic | `AVG_ORGANIC_EFFECTIVENESS_V2` | | Avg. Engagement Rate - Organic | The average percentage of people who engaged with a post after seeing it | Organic | `AVG_ORGANIC_ENGAGEMENT_RATE_V2` | | Avg. Viewers - Total | The average number of unique accounts that have viewed your posts at least once. Note: Values before July 31, 2025 reflect Reach, which Meta replaced with Viewers. | Organic + Promoted | `AVG_PAID_AND_ORGANIC_POST_REACH_V2` | | Avg. Effectiveness - Paid | The average percentage of viewers who saw your posts and engaged with them | Promoted | `AVG_PAID_EFFECTIVENESS_V2` | | Avg. Engagement Rate - Paid | The average percentage of people who engaged with a post after seeing it | Promoted | `AVG_PAID_ENGAGEMENT_RATE_V2` | | Avg. Reach - Paid | The average number of unique accounts that have viewed your posts at least once. Note: This metric uses Reach from Ad campaigns. | Promoted | `AVG_PAID_POST_REACH_V2` | | Avg. CTR - Paid | The average percentage of times people clicked your posts after seeing them | Promoted | `CLICK_THROUGH_RATE` | | Comments - Total - All Posts | The number of comments any of your posts received during the Reporting Period | Organic + Promoted | `COMMENTS_ALL_POSTS` | | Post Sentiment - Negative | The percentage of posts published during the Reporting Period with an overall negative comment sentiment | Organic + Promoted | `COMMENT_SENTIMENT_NEGATIVE_RATE` | | Post Sentiment - Negative | The percentage of posts with a negative overall comment sentiment | Organic | `COMMENT_SENTIMENT_NEGATIVE_RATE_ORGANIC` | | Post Sentiment - Negative | The percentage of posts with a negative overall comment sentiment | Promoted | `COMMENT_SENTIMENT_NEGATIVE_RATE_PROMOTED` | | Post Sentiment - Neutral | The percentage of posts published during the Reporting Period with an overall neutral comment sentiment | Organic + Promoted | `COMMENT_SENTIMENT_NEUTRAL_RATE` | | Post Sentiment - Neutral | The percentage of posts with a neutral overall comment sentiment | Organic | `COMMENT_SENTIMENT_NEUTRAL_RATE_ORGANIC` | | Post Sentiment - Neutral | The percentage of posts with a neutral overall comment sentiment | Promoted | `COMMENT_SENTIMENT_NEUTRAL_RATE_PROMOTED` | | Post Sentiment - Positive | The percentage of posts published during the Reporting Period with an overall positive comment sentiment | Organic + Promoted | `COMMENT_SENTIMENT_POSITIVE_RATE` | | Post Sentiment - Positive | The percentage of posts with a positive overall comment sentiment | Organic | `COMMENT_SENTIMENT_POSITIVE_RATE_ORGANIC` | | Post Sentiment - Positive | The percentage of posts with a positive overall comment sentiment | Promoted | `COMMENT_SENTIMENT_POSITIVE_RATE_PROMOTED` | | Avg. CPC - Paid | The average cost per click on your posts | Promoted | `COST_PER_CLICK` | | Avg. CPM - Paid | The average cost per 1,000 impressions on your posts | Promoted | `COST_PER_MILE` | | Followers - Growth Rate | The percentage your Page's Followers increased by during the Reporting Period. Followers Growth Rate = (New Followers - Old Followers) / Old Followers x 100% | | `FOLLOWER_GROWTH_RATE` | | Link Clicks - Total | The number of times people clicked on the link in a post or link preview for posts published during the Reporting Period | Organic + Promoted | `LINK_CLICKS` | | Followers - Net New | The net new number of Followers your page has gained | | `NET_NEW_FOLLOWERS` | | Number of Posts | The number of posts you've published during the reporting period | Organic + Promoted | `NUMBER_OF_POSTS` | | Number of Posts | The number of posts you've published during the reporting period | Promoted | `NUMBER_OF_POSTS_PAID` | | Comments - Organic | The number of comments received on posts published during the reporting period | Organic | `ORGANIC_COMMENTS` | | Engagements - Organic | The total number of engagements your posts received | Organic | `ORGANIC_ENGAGEMENTS_POSTS_V2` | | Number of Posts | The number of posts you've published during the reporting period | Organic | `ORGANIC_NUMBER_OF_POSTS` | | Reactions - Organic | The total number of reactions your posts published during the reporting period received | Organic | `ORGANIC_REACTIONS` | | Shares - Organic | The number of times your posts published during the reporting period were shared | Organic | `ORGANIC_SHARES` | | Video Views - Organic | The number of times your videos were viewed | Organic | `ORGANIC_VIDEO_VIEWS` | | Views - Organic | The number of times your posts were viewed | Organic | `ORGANIC_VIEWS_BY_POST` | | Other Clicks - Total | The number of clicks on your posts, including links and other clickable elements on posts published during the reporting period | Organic + Promoted | `OTHER_CLICKS` | | Views - Organic - All Posts | The number of times your posts were viewed or displayed during the reporting period | Organic | `PAGE_VIEWS_ORGANIC` | | Views - Paid - All Posts | The number of times your posts were viewed or displayed during the reporting period | Promoted | `PAGE_VIEWS_PAID` | | Views - Total - All Posts | The number of times your posts were viewed or displayed during the reporting period | Organic + Promoted | `PAGE_VIEWS_PAID_AND_ORGANIC` | | Video Complete Views - Total | The number of times your video was played from the beginning to 95% or more of its length | Organic + Promoted | `PAID_AND_ORGANIC_VIDEO_COMPLETE_VIEWS` | | Video Views - Total | The number of times your videos were viewed | Organic + Promoted | `PAID_AND_ORGANIC_VIDEO_VIEWS` | | Views - Total | The number of times your posts were viewed | Organic + Promoted | `PAID_AND_ORGANIC_VIEWS_BY_POST` | | Comments - Paid | The number of comments your posts received | Promoted | `PAID_COMMENTS` | | Avg. Cost Per Thruplay - Paid | The average cost per Thruplay for your videos | Promoted | `PAID_COST_PER_THRUPLAY` | | Engagements - Paid | The total number of engagements your posts received | Promoted | `PAID_ENGAGEMENTS_POSTS` | | Avg. Frequency - Paid | The average number of times people saw your promoted posts | Promoted | `PAID_FREQUENCY` | | Reactions - Paid | The number of reactions your posts received. Reactions include Like, Love, Care, Haha, Wow, Sad and Angry. | Promoted | `PAID_REACTIONS` | | Shares - Paid | The number of times your posts were shared | Promoted | `PAID_SHARES` | | ThruPlays - Paid | The number of times your posts were watched to completion or for at least 15 seconds | Promoted | `PAID_THRUPLAYS` | | Video Complete Views - Paid | The number of times your videos were played from the beginning to 95%, or more, of their length | Promoted | `PAID_VIDEO_COMPLETE_VIEWS` | | Video Plays 25% - Paid | The number of times your video was played to 25% of its length, including plays that skipped to this point | Promoted | `PAID_VIDEO_PLAYS_25` | | Video Plays 50% - Paid | The number of times your video was played to 50% of its length, including plays that skipped to this point | Promoted | `PAID_VIDEO_PLAYS_50` | | Video Plays 75% - Paid | The number of times your video was played to 75% of its length, including plays that skipped to this point | Promoted | `PAID_VIDEO_PLAYS_75` | | Video Views - Paid | The number of times your videos were viewed | Promoted | `PAID_VIDEO_VIEWS` | | Views - Paid | The number of times your posts were viewed | Promoted | `PAID_VIEWS_BY_POST` | | Photo View Clicks - Total | The number of times users clicked on your photos published during the reporting period | Organic + Promoted | `PHOTO_VIEW_CLICKS` | | Post Clicks - Total | The number of times a user clicked anywhere on your posts published during the reporting period | Organic + Promoted | `POST_CLICKS` | | Reactions - Total | The number of times people clicked on like, care, love, wow, haha, sad, and anger reactions on posts published during the Reporting Period | Organic + Promoted | `REACTIONS` | | Reactions - Total - All Posts | The number of reactions your posts received. Reactions include Like, Love, Care, Haha, Wow, Sad and Angry. | Organic + Promoted | `REACTIONS_ALL_POSTS` | | Plays - Total | The number of times your videos published during the Reporting Period were initially played. This excludes replays | Organic + Promoted | `REELS_BLUE_REELS_PLAYS_COUNT` | | Replays - Total | The number of rewatches your videos published during the Reporting Period received in the same session | Organic + Promoted | `REELS_FB_REELS_REPLAY_COUNT` | | Avg. Time Watched - Total | The average time your videos published during the Reporting Period were played during a single viewing | Organic + Promoted | `REELS_POST_VIDEO_AVG_TIME_WATCHED` | | Follows - Total | The number of viewers who followed your Page after viewing your videos published during the Reporting Period | Organic + Promoted | `REELS_POST_VIDEO_FOLLOWERS` | | Total Time Watched - Total | The sum of time that viewers watched your videos published during the Reporting Period | Organic + Promoted | `REELS_POST_VIDEO_VIEW_TIME` | | Reactions - Angry - Total | The number of times people used an Angry reaction to your post | Organic + Promoted | `REEL_REACTION_ANGRY` | | Reactions - Haha - Total | The number of times people used a Haha reaction to your post | Organic + Promoted | `REEL_REACTION_HAHA` | | Reactions - Like - Total | The number of times people used a Like or a Care reaction to your post | Organic + Promoted | `REEL_REACTION_LIKE` | | Reactions - Love - Total | The number of times people used a Love reaction to your post | Organic + Promoted | `REEL_REACTION_LOVE` | | Reactions - Sad - Total | The number of times people used a Sad reaction to your post | Organic + Promoted | `REEL_REACTION_SAD` | | Reactions - Wow - Total | The number of times people used a Wow reaction to your post | Organic + Promoted | `REEL_REACTION_WOW` | | Shares - Total | The number of times your posts were shared | Organic + Promoted | `SHARES` | | Comments - Total | The number of comments your posts received | Organic + Promoted | `TOTAL_COMMENTS` | | Engagements - Total - All Posts | The total number of reactions, comments, shares, and post clicks on all posts during the Reporting Period | Organic + Promoted | `TOTAL_ENGAGEMENTS` | | Engagements - Total | The total number of engagements your posts received | Organic + Promoted | `TOTAL_ENGAGEMENTS_POSTS_V2` | | Followers | The total number of Followers your Facebook Page has | | `TOTAL_FOLLOWERS` | | Amount Spent - Paid | The total amount of money you've spent boosting your posts. Due to API delays, recent spend figures may be estimated for up to 48 hours. | Promoted | `TOTAL_SPENT` | | Total Social Impact | 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` | | Video Complete Views - Organic | The number of times your videos published during the Reporting Period were played from the beginning to 95%, or more, of its length | Organic | `VIDEO_COMPLETE_VIEWS` | | Viewers - All Posts | The number of unique accounts that viewed any content on your Page. Content includes reels, posts, stories, live videos and ads. | | `VIEWERS` | | Metric Name | Description | Post Types | Metric API Name | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------------------------------------------ | | Avg. Completion Rate - Total | The average percentage of viewers that watched each organic and promoted video published during the reporting period to completion | Organic + Promoted | `AVG_COMPLETION_RATE` | | Avg. Engagement Rate (Reach) - Total | The average Engagement Rate of your organic and promoted videos published during the reporting period. Engagement Rate = Total Engagements / Reach | Organic + Promoted | `AVG_ENGAGEMENT_RATE` | | Avg. Entertainment Score - Total | The average Entertainment Score of your organic and promoted videos during the reporting period. The score is on a scale of 0 to 10 and takes the engagement and retention rate of each video into account. Scores are generated 48 hours after publishing. | Organic + Promoted | `AVG_ENTERTAINMENT_SCORE` | | Avg. FYP Views - Total | The average percentage of views that came from the For You page for organic and promoted videos published during the reporting period | Organic + Promoted | `AVG_FYP_VIEWS` | | Avg. Likes - Organic | The average number of likes your organic posts received. Important: This metric stops updating when ad promotions end. | Organic | `AVG_ORGANIC_LIKES` | | Avg. Reach - Est. Organic | The estimated number of people who watched your video at least once through organic reach. If not all Ad accounts are connected, organic reach may be underreported. Important: This metric stops updating when ad promotions end. Due to API limitations, the sum of organic + promoted Reach may not match the Reach metric once the promotions stop. | ESTIMATED\_ORGANIC | `AVG_ORGANIC_REACH` | | Avg. Shares - Organic | The average number of times your organic posts were shared. Important: This metric stops updating when ad promotions end. | Organic | `AVG_ORGANIC_SHARES` | | Avg. Video Views - Est. Organic | The estimated average number of times viewers watched your video through organic reach. Includes replays and multiple views from the same viewer. Important: This metric stops updating when ad promotions end. Due to API limitations, this is an estimated value and the sum of organic + promoted views may not match the Video Views metric once the promotions end. | ESTIMATED\_ORGANIC | `AVG_ORGANIC_VIDEO_VIEWS` | | Avg. Engagement Rate (Reach) - Paid | The percentage of people who engaged with your promoted posts after seeing them. Important: This metric stops updating when ad promotions end. | Promoted | `AVG_PAID_ENGAGEMENT_RATE` | | Avg. Likes - Paid | The average number of likes your promoted posts received. Important: This metric stops updating when ad promotions end. | Promoted | `AVG_PAID_LIKES` | | Avg. Reach - Paid | The estimated number of people who watched your video at least once through promoted reach. Important: This metric stops updating when ad promotions end. Due to API limitations, the sum of organic + promoted Reach may not match the Reach metric once the promotions stop. | Promoted | `AVG_PAID_REACH` | | Avg. Shares - Paid | The average number of times your promoted posts were shared. Important: This metric stops updating when ad promotions end. | Promoted | `AVG_PAID_SHARES` | | Avg. Video Views - Paid | The estimated average number of times viewers watched your video through promoted reach. Includes replays and multiple views from the same viewer. Important: This metric stops updating when ad promotions end. Due to API limitations, this is an estimated value and the sum of organic + promoted views may not match the Video Views metric once the promotions end. | Promoted | `AVG_PAID_VIDEO_VIEWS` | | Avg. Reach - Total | The average Reach of your organic and promoted videos published during the reporting period | Organic + Promoted | `AVG_REACH` | | Avg. Retention Rate - Total | The average Retention Rate of the organic and promoted videos published during the reporting period | Organic + Promoted | `AVG_RETENTION_RATE` | | Avg. Time Watched - Total | The average amount of time viewers spent watching your organic and promoted videos published during the reporting period | Organic + Promoted | `AVG_TIME_WATCHED` | | Avg. Comments - Total | The average number of comments your organic and promoted videos published during the reporting period received | Organic + Promoted | `AVG_TOTAL_COMMENTS` | | Avg. Engagements - Total | The average number of engagements your organic and promoted videos published during the reporting period received. Total Engagements = Likes + Comments + Shares | Organic + Promoted | `AVG_TOTAL_ENGAGEMENTS` | | Avg. Likes - Total | The average number of likes your organic and promoted videos published during the reporting period received | Organic + Promoted | `AVG_TOTAL_LIKES` | | Avg. Shares - Total | The average number of shares your organic and promoted videos published during the reporting period received | Organic + Promoted | `AVG_TOTAL_SHARES` | | Avg. Traffic - Following Page - Total | The average percentage of video views coming from the Following Page for videos published during the reporting period | Organic + Promoted | `AVG_TRAFFIC_FROM_FOLLOWING_PAGE` | | Avg. Traffic - Hashtag - Total | The average percentage of video views coming from a Hashtag for videos published during the reporting period | Organic + Promoted | `AVG_TRAFFIC_FROM_HASHTAG` | | Avg. Traffic - Personal Profile - Total | The average percentage of video views coming from your Personal profile for videos published during the reporting period | Organic + Promoted | `AVG_TRAFFIC_FROM_PERSONAL_PROFILE` | | Avg. Traffic - Search - Total | The average percentage of video views coming from Search for videos published during the reporting period | Organic + Promoted | `AVG_TRAFFIC_FROM_SEARCH` | | Avg. Traffic - Sound - Total | The average percentage of video views coming from a Sound for videos published during the reporting period | Organic + Promoted | `AVG_TRAFFIC_FROM_SOUND` | | Avg. Video Duration - Total | The average duration of your organic and promoted videos published during the reporting period | Organic + Promoted | `AVG_VIDEO_DURATION` | | Avg. Video Views - Total | The average number of times your organic and promoted videos published during the reporting period were viewed | Organic + Promoted | `AVG_VIDEO_VIEWS` | | Post Sentiment - Negative - Total | The percentage of posts published during the reporting period with an overall negative comment sentiment | Organic + Promoted | `COMMENT_SENTIMENT_NEGATIVE_RATE` | | Post Sentiment - Negative - Organic | The percentage of posts with a negative overall comment sentiment | Organic | `COMMENT_SENTIMENT_NEGATIVE_RATE_ORGANIC` | | Post Sentiment - Negative - Paid | The percentage of posts with a negative overall comment sentiment | Promoted | `COMMENT_SENTIMENT_NEGATIVE_RATE_PROMOTED` | | Post Sentiment - Neutral - Total | The percentage of posts published during the reporting period with an overall neutral comment sentiment | Organic + Promoted | `COMMENT_SENTIMENT_NEUTRAL_RATE` | | Post Sentiment - Neutral - Organic | The percentage of posts with a neutral overall comment sentiment | Organic | `COMMENT_SENTIMENT_NEUTRAL_RATE_ORGANIC` | | Post Sentiment - Neutral - Paid | The percentage of posts with a neutral overall comment sentiment | Promoted | `COMMENT_SENTIMENT_NEUTRAL_RATE_PROMOTED` | | Post Sentiment - Positive - Total | The percentage of posts published during the reporting period with an overall positive comment sentiment | Organic + Promoted | `COMMENT_SENTIMENT_POSITIVE_RATE` | | Post Sentiment - Positive - Organic | The percentage of posts with a positive overall comment sentiment | Organic | `COMMENT_SENTIMENT_POSITIVE_RATE_ORGANIC` | | Post Sentiment - Positive - Paid | The percentage of posts with a positive overall comment sentiment | Promoted | `COMMENT_SENTIMENT_POSITIVE_RATE_PROMOTED` | | Engagements - Total - All Posts | The total number of engagements any of your organic and promoted videos received during the reporting period.Total Engagements = Likes + Comments + Shares | Organic + Promoted | `ENGAGEMENTS` | | Followers - Growth Rate | The percentage your total followers increased by during the reporting period. Follower Growth Rate = (Current Period - Previous Period) / Previous Period x 100% | | `FOLLOWER_GROWTH_RATE` | | LikeShop Clicks - All Posts | The number of clicks on your products on your LikeShop feed | | `LIKESHOP_CLICKS` | | LikeShop Contact Submissions - All Posts | The number of email submissions during the reporting period | | `LIKESHOP_CONTACT_SUBMISSIONS` | | LikeShop CTR - All Posts | The percentage of times people clicked your product links after viewing your post | | `LIKESHOP_CTR` | | LikeShop Posts | The number of posts you've published during the reporting period that include product links. These are the posts visible on your LikeShop. | | `LIKESHOP_POSTS` | | LikeShop Views - All Posts | The number of times your posts were displayed on a person's screen. This includes repeat views. | | `LIKESHOP_VIEWS` | | Followers - Net New | The net new number of people who have followed your account during the reporting period | | `NET_NEW_FOLLOWERS` | | Number of Posts - Organic | The number of organic posts you've published during the reporting period | Organic | `NUMBER_OF_ORGANIC_POSTS` | | Number of Posts - Paid | The number of promoted posts you've published during the reporting period | Promoted | `NUMBER_OF_PAID_POSTS` | | Number of Posts - Total | The number of posts you've published during the reporting period | Organic + Promoted | `NUMBER_OF_POSTS` | | Comments - Total - All Posts | The number of comments any of your organic and promoted videos received during the reporting period | Organic + Promoted | `ORGANIC_COMMENTS` | | Likes - Total - All Posts | The number of likes any of your organic and promoted videos received during the reporting period | Organic + Promoted | `ORGANIC_LIKES` | | Likes - Organic | The number of likes your organic posts received. Important: This metric stops updating when ad promotions end. | Organic | `ORGANIC_LIKES_POSTS` | | Shares - Organic | The number of times your organic posts were shared. Important: This metric stops updating when ad promotions end. | Organic | `ORGANIC_SHARES` | | Video Views - Est. Organic | The estimated number of times viewers watched your video through organic reach. Includes replays and multiple views from the same viewer. Important: This metric stops updating when ad promotions end. Due to API limitations, this is an estimated value and the sum of organic + promoted views may not match the Video Views metric once the promotions end. | ESTIMATED\_ORGANIC | `ORGANIC_VIEWS` | | Engagements - Paid | The total number of engagements your promoted posts received. Important: This metric stops updating when ad promotions end. | Promoted | `PAID_ENGAGEMENTS` | | Likes - Paid | The number of likes your promoted posts received. Important: This metric stops updating when ad promotions end. | Promoted | `PAID_LIKES` | | Shares - Paid | The number of times your promoted posts were shared. Important: This metric stops updating when ad promotions end. | Promoted | `PAID_SHARES` | | Video Views - Paid | The estimated number of times viewers watched your video through promoted reach. Includes replays and multiple views from the same viewer. Important: This metric stops updating when ad promotions end. Due to API limitations, this is an estimated value and the sum of organic + promoted views may not match the Video Views metric once the promotions end. | Promoted | `PAID_VIDEO_VIEWS` | | Avg. Engagement Rate (Views) - Paid | The percentage of people who engaged with your promoted posts after seeing them. Important: This metric stops updating when ad promotions end. | Promoted | `PAID_VIEWS_BASED_ENGAGEMENT_RATE` | | Profile Views | The number of times people viewed your profile | | `PROFILE_VIEWS` | | Shares - Total - All Posts | The number of times any of your organic and promoted videos were shared during the reporting period | Organic + Promoted | `SHARES` | | Comments - Total | The number of comments your organic and promoted videos published during the reporting period received | Organic + Promoted | `TOTAL_COMMENTS` | | Engagements - Total | The number of engagements your organic and promoted videos published during the reporting period received Total Engagements = Likes + Comments + Shares | Organic + Promoted | `TOTAL_ENGAGEMENTS` | | Favorites - Total | The total number of times your posts have been added to favorites | Organic + Promoted | `TOTAL_FAVORITES` | | Followers | The total number of followers you have on this channel | | `TOTAL_FOLLOWERS` | | Follows - Total | The number of viewers who started following you after viewing your posts | Organic + Promoted | `TOTAL_FOLLOWS` | | Likes - Total | The number of likes your organic and promoted videos published during the reporting period received | Organic + Promoted | `TOTAL_LIKES` | | Follows - Organic | The number of viewers who started following you after viewing your posts. Important: This metric stops updating when ad promotions end. | Organic | `TOTAL_ORGANIC_FOLLOWS` | | Profile Views - Organic | The number of profile views generated by your posts. Important: This metric stops updating when ad promotions end. Data may be delayed by 48 hours. | Organic | `TOTAL_ORGANIC_PROFILE_VIEWS` | | Follows - Paid | The number of viewers who started following you after viewing your posts. Important: This metric stops updating when ad promotions end. | Promoted | `TOTAL_PAID_FOLLOWS` | | Profile Views - Paid | The number of profile views generated by your posts. Important: This metric stops updating when ad promotions end. Data may be delayed by 48 hours. | Promoted | `TOTAL_PAID_PROFILE_VIEWS` | | Profile Views - Total | The total number of profile views generated by your posts. Data may be delayed by 48 hours. | Organic + Promoted | `TOTAL_PROFILE_VIEWS` | | Shares - Total | The number of times your posts published during the reporting period were shared | Organic + Promoted | `TOTAL_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` | | Video Duration - Total | The length of your published videos | Organic + Promoted | `TOTAL_VIDEO_DURATION` | | Video Views - Total | The number of times your organic and promoted videos published during the reporting period were viewed | Organic + Promoted | `TOTAL_VIDEO_VIEWS` | | Video Views - Total - All Posts | The number of times any of your organic and promoted videos were viewed during the reporting period | Organic + Promoted | `VIDEO_VIEWS` | | Avg. Engagement Rate (Views) - Total | The percentage of people who engaged with your posts after seeing them | Organic + Promoted | `VIEWS_BASED_ENGAGEMENT_RATE` | | Total Time Watched - Total | The total amount of time viewers spent watching your videos | Organic + Promoted | `WATCH_TIME` | | Metric Name | Description | Post Types | Metric API Name | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | --------------------------------- | | Engagement Rate - All Posts | The average engagement rate of your tweets during the reporting period. Engagement Rate = Total Engagements / Impressions | Organic | `AVG_ENGAGEMENT_RATE` | | Post Sentiment - Negative | The percentage of posts published during the reporting period with an overall negative comment sentiment | Organic | `COMMENT_SENTIMENT_NEGATIVE_RATE` | | Post Sentiment - Neutral | The percentage of posts published during the reporting period with an overall neutral comment sentiment | Organic | `COMMENT_SENTIMENT_NEUTRAL_RATE` | | Post Sentiment - Positive | The percentage of posts published during the reporting period with an overall positive comment sentiment | Organic | `COMMENT_SENTIMENT_POSITIVE_RATE` | | Followers - Growth Rate | The percentage your followers increased by during the reporting period. Follower Growth Rate = (New Followers - Old Followers) / Old Followers x 100% | | `FOLLOWER_GROWTH_RATE` | | Impressions - All Posts | The number of times your posts were viewed or displayed | Organic | `IMPRESSIONS` | | Impressions | The number of times your posts published during the reporting period were displayed | Organic | `IMPRESSIONS_BY_POST` | | Likes - All Posts | The number of likes your Tweets received during the reporting period | Organic | `LIKES` | | Link Clicks - All Posts | The number of times links on your Tweets were clicked during the reporting period | Organic | `LINK_CLICKS` | | Followers - Net New | The net new number of people who have followed your account | | `NET_NEW_FOLLOWERS` | | Number of Posts | The number of posts you've published during the reporting period | Organic | `NUMBER_OF_POSTS` | | Video Views - All Posts | The number of times your videos were viewed | Organic | `ORGANIC_VIDEO_VIEWS` | | Profile Clicks - All Posts | The number of times your profile has been clicked from Tweets during the reporting period | Organic | `PROFILE_CLICKS` | | Quote Posts - All Posts | The number of times your Tweets were Quote Tweeted during the reporting period | Organic | `QUOTE_TWEETS` | | Replies - All Posts | The number of replies your Tweets received during the reporting period | Organic | `REPLIES` | | Reposts - All Posts | The number of times your Tweets were Retweeted during the reporting period | Organic | `RETWEETS` | | Avg. Engagement Rate | The average engagement rate of your tweets published during the reporting period. Engagement Rate = Total Engagements / Impressions | Organic | `TOTAL_AVG_ENGAGEMENT_RATE` | | Engagements - All Posts | The total number of times a user interacted with your tweets during the reporting period, including Retweets, replies, likes, hashtags, or link clicks | Organic | `TOTAL_ENGAGEMENTS` | | Engagements | The total number of engagements your posts published during the reporting period received Engagements = Likes + Dislikes + Comments + Shares | Organic | `TOTAL_ENGAGEMENTS_POSTS` | | Followers | The total number of followers you have on this channel | | `TOTAL_FOLLOWERS` | | Total Reposts - All Posts | The total number of times your Tweets were Retweeted during the reporting period. Total Retweets = Retweets + Quote Tweets | Organic | `TOTAL_RETWEETS` | | 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` | | Video Views | The number of times your videos were viewed | Organic + Promoted | `TOTAL_VIDEO_VIEWS` | | Metric Name | Description | Post Types | Metric API Name | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----------------------------------- | | Avg. Card Click Rate - Total | The average cards click-through-rate on your organic and promoted videos published during the Reporting Period. Card Click Rate = Card Clicks / Card Impressions | Organic + Promoted | `AVG_CARD_CLICK_RATE` | | Avg. Card Teaser Click Rate - Total | The average card teasers click-through-rate on your organic and promoted videos published during the Reporting Period. Card Teaser Click Rate = Card Teaser Clicks / Card Teaser Impressions | Organic + Promoted | `AVG_CARD_TEASER_CLICK_RATE` | | Avg. View Duration - Total - All Posts | The average amount of time viewers spent watching any of your organic and promoted videos during the Reporting Period | Organic + Promoted | `AVG_VIEW_DURATION` | | Avg. Percentage Viewed - Total - All Posts | The average retention rate of your organic and promoted videos during the Reporting Period | Organic + Promoted | `AVG_VIEW_PERCENTAGE` | | Card Clicks - Total - All Posts | The number of times the cards were clicked on all your organic and promoted videos during the Reporting Period | Organic + Promoted | `CARD_CLICKS` | | Avg. Card Click Rate - Total - All Posts | The average cards click-through-rate on all your organic and promoted videos during the Reporting Period. Card Click Rate = Card Clicks / Card Impressions | Organic + Promoted | `CARD_CLICK_RATE` | | Card Impressions - Total - All Posts | The number of times cards were displayed on all your organic and promoted videos during the Reporting Period | Organic + Promoted | `CARD_IMPRESSIONS` | | Card Teaser Clicks - Total - All Posts | The number of times the card teasers were clicked on all your organic and promoted videos during the Reporting Period | Organic + Promoted | `CARD_TEASER_CLICKS` | | Avg. Card Teaser Click Rate - Total - All Posts | The average card teasers click-through-rate on all your organic and promoted videos during the Reporting Period. Card Teaser Click Rate = Card Teaser Clicks / Card Teaser Impressions | Organic + Promoted | `CARD_TEASER_CLICK_RATE` | | Card Teaser Impressions - Total - All Posts | The number of times card teasers were displayed on all your organic and promoted videos during the Reporting Period | Organic + Promoted | `CARD_TEASER_IMPRESSIONS` | | Comments - Total - All Posts | The number of comments any of your organic and promoted videos received during the Reporting Period | Organic + Promoted | `COMMENTS` | | Post Sentiment - Negative | The percentage of posts published during the Reporting Period with an overall negative comment sentiment | Organic + Promoted | `COMMENT_SENTIMENT_NEGATIVE_RATE` | | Post Sentiment - Neutral | The percentage of posts published during the Reporting Period with an overall neutral comment sentiment | Organic + Promoted | `COMMENT_SENTIMENT_NEUTRAL_RATE` | | Post Sentiment - Positive | The percentage of posts published during the Reporting Period with an overall positive comment sentiment | Organic + Promoted | `COMMENT_SENTIMENT_POSITIVE_RATE` | | Dislikes - Total - All Posts | The number of dislikes any of your organic and promoted videos received during the Reporting Period | Organic + Promoted | `DISLIKES` | | Engagements - Total - All Posts | The total number of engagements any of your organic and promoted videos received during the Reporting Period. Total Engagements = Likes + Dislikes + Comments + Shares | Organic + Promoted | `ENGAGEMENTS` | | Premium Watch Time - Total - All Posts | The total amount of time your organic and promoted videos were viewed during the Reporting Period by YouTube Premium members | Organic + Promoted | `ESTIMATED_PREMIUM_SECONDS_WATCHED` | | Watch Time - Total - All Posts | The total amount of time that viewers watched any organic and promoted videos on your channel during the Reporting Period | Organic + Promoted | `ESTIMATED_SECONDS_WATCHED` | | Likes - Total - All Posts | The number of likes any of your organic and promoted videos received during the Reporting Period | Organic + Promoted | `LIKES` | | Number of Posts | The number of posts you've published during the reporting period | Organic + Promoted | `NUMBER_OF_POSTS` | | Premium Views - Total - All Posts | The number of times your organic and promoted videos were viewed during the Reporting Period by YouTube Premium members | Organic + Promoted | `PREMIUM_VIEWS` | | Shares - Total - All Posts | The number of shares any of your organic and promoted videos received during the Reporting Period | Organic + Promoted | `SHARES` | | Subscribers - Lost | The total number of people who unsubscribed from your channel | | `SUBSCRIBERS_LOST` | | Subscribers - Net New | The net new number of users who have subscribed to your channel during the Reporting Period | | `SUBSCRIBERS_NET_NEW` | | Subscribers | The number of users who have subscribed to your channels by the last day of the Reporting Period | | `SUBSCRIBERS_TOTAL` | | Subscribers - Growth Rate | The percentage your subscribers have increased by during the Reporting Period. Subscriber Growth Rate = (Current Period - Previous Period) / Previous Period x 100% | | `SUBSCRIBER_GROWTH_RATE` | | Avg. View Duration - Total | The average amount of time viewers spent watching your organic and promoted videos published during the Reporting Period | Organic + Promoted | `TOTAL_AVG_VIEW_DURATION` | | Avg. Percentage Viewed - Total | The average retention rate of your organic and promoted videos published during the Reporting Period | Organic + Promoted | `TOTAL_AVG_VIEW_PERCENTAGE` | | Card Clicks - Total | The number of times the cards were clicked on your organic and promoted videos published during the Reporting Period | Organic + Promoted | `TOTAL_CARD_CLICKS` | | Card Impressions - Total | The number of times cards were displayed on your organic and promoted videos published during the Reporting Period | Organic + Promoted | `TOTAL_CARD_IMPRESSIONS` | | Card Teaser Clicks - Total | The number of times the card teasers were clicked on your organic and promoted videos published during the Reporting Period | Organic + Promoted | `TOTAL_CARD_TEASER_CLICKS` | | Card Teaser Impressions - Total | The number of times card teasers were displayed on your organic and promoted videos published during the Reporting Period | Organic + Promoted | `TOTAL_CARD_TEASER_IMPRESSIONS` | | Comments - Total | The total number of comments your organic and promoted videos published during the Reporting Period received | Organic + Promoted | `TOTAL_COMMENTS` | | Dislikes - Total | The total number of dislikes your organic and promoted videos published during the Reporting Period received | Organic + Promoted | `TOTAL_DISLIKES` | | Engagements - Total | The total number of engagements your organic and promoted videos published during the Reporting Period received. Total Engagements = Likes + Dislikes + Comments + Shares | Organic + Promoted | `TOTAL_ENGAGEMENTS` | | Watch Time - Total | The total amount of time that viewers watched organic and promoted videos on your channel that were published during the Reporting Period | Organic + Promoted | `TOTAL_ESTIMATED_SECONDS_WATCHED` | | Premium Watch Time - Total | The total amount of time your organic and promoted videos published during the Reporting Period were viewed by YouTube Premium members | Organic + Promoted | `TOTAL_EST_PREMIUM_SECONDS_WATCHED` | | Likes - Total | The total number of likes your organic and promoted videos published during the Reporting Period received | Organic + Promoted | `TOTAL_LIKES` | | Premium Views - Total | The number of times your organic and promoted videos published during the Reporting Period were viewed by YouTube Premium members | Organic + Promoted | `TOTAL_PREMIUM_VIEWS` | | Shares - Total | The total number of shares your organic and promoted videos published during the Reporting Period received | Organic + Promoted | `TOTAL_SHARES` | | Subscribers - Gained | The number of viewers who subscribed while watching your videos | Organic + Promoted | `TOTAL_SUBSCRIBERS_GAINED` | | Subscribers - Lost | The number of viewers who unsubscribed while watching your videos | Organic + Promoted | `TOTAL_SUBSCRIBERS_LOST` | | 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` | | Added to Playlist - Total | The total number of times your organic and promoted videos published during the Reporting Period were added to a playlist | Organic + Promoted | `TOTAL_VIDEOS_ADDED_TO_PLAYLIST` | | Video Views - Total | The total number of times your organic and promoted videos published during the Reporting Period were viewed | Organic + Promoted | `TOTAL_VIDEO_VIEWS` | | Added to Playlist - Total - All Posts | The number of times any of your organic and promoted videos were added to any YouTube playlists during the Reporting Period | Organic + Promoted | `VIDEOS_ADDED_TO_PLAYLIST` | | Video Views - Total - All Posts | The number of times your organic and promoted videos were viewed during the Reporting Period | Organic + Promoted | `VIEWS` | | Metric Name | Description | Post Types | Metric API Name | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | --------------------------- | | Engagement Rate - All Posts | The average percentage of your audience that engaged with your Pins during the Reporting Period. Engagement Rate = (Pin Clicks + Outbound Clicks + Saves) / Impressions. | Organic | `AVG_ENGAGEMENT_RATE` | | Avg. Watch Time | The average time spent watching your video Pins | Organic | `AVG_WATCH_TIME` | | Pin Clicks - All Posts | The number of times your Pins were clicked to view more details during the Reporting Period | Organic | `CLOSEUPS` | | Engagements | The total number of engagements your Pins received | Organic | `ENGAGEMENTS` | | Followers - Growth Rate | The percentage your followers increased by over the comparison period | | `FOLLOWER_GROWTH_RATE` | | Impressions - All Posts | The number of times your Pins were viewed or displayed | Organic | `IMPRESSIONS` | | Outbound Clicks - All Posts | The number of times the links in your Pins were clicked during the Reporting Period | Organic | `LINK_CLICKS` | | Followers - Net New | The net new number of people who have followed your account | | `NET_NEW_FOLLOWERS` | | Number of Posts | The number of posts you've published during the reporting period | Organic | `NUMBER_OF_POSTS` | | Saves - All Posts | The number of times users saved your Pins during the reporting period | Organic | `SAVES` | | Avg. Engagement Rate | The average percentage of your audience that engaged with your Pins published during the reporting period. Engagement Rate = (Pin Clicks + Outbound Clicks + Saves) / Impressions. | Organic | `TOTAL_AVG_ENGAGEMENT_RATE` | | Engagements - All Posts | The total number of organic engagements your images, videos, and product pins received during the reporting period | Organic | `TOTAL_ENGAGEMENTS` | | Followers | The total number of followers you have on this channel | | `TOTAL_FOLLOWERS` | | 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` | | Video Views | The number of views lasting at least two seconds with 50% of the video pin visible from post published during the reporting period | Organic | `TOTAL_VIDEO_VIEWS` | | Metric Name | Description | Post Types | Metric API Name | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | -------------------------------- | | Avg. CTR | The average percentage of your audience that clicked on posts published during the reporting period. Click Through Rate = Clicks / Impressions | Organic | `AVG_CLICK_THROUGH_RATE_BY_POST` | | Avg. Engagement Rate - All Posts | The average engagement rate of all your posts during the reporting period. Engagement Rate = (Clicks + Reactions + Comments + Reposts) / Impressions | Organic | `AVG_ENGAGEMENT_RATE_ALL_POSTS` | | Avg. Engagement Rate | The average engagement rate of your posts that were published during the Reporting Period. Engagement Rate = (Clicks + Reactions + Comments + Reposts) / Impressions | Organic | `AVG_ENGAGEMENT_RATE_BY_POST` | | Avg. Unique Impressions | The average number of unique LinkedIn members that saw your posts published during the reporting period. Similar to Reach | Organic | `AVG_UNIQUE_IMPRESSIONS_BY_POST` | | Clicks - All Posts | The number of times people clicked on any of your posts during the reporting period | Organic | `CLICKS_ALL_POSTS` | | Clicks | The number of times people clicked on your posts published during the reporting period | Organic | `CLICKS_BY_POST` | | Avg. CTR - All Posts | The average percentage of your audience that clicked on your posts during the Reporting Period. Click Through Rate = Clicks / Impressions | Organic | `CLICK_THROUGH_RATE` | | Comments - All Posts | The number of comments any of your posts received during the reporting period | Organic | `COMMENTS_ALL_POSTS` | | Comments | The number of comments received on posts published during the reporting period | Organic | `COMMENTS_BY_POST` | | Engagements - All Posts | The total number of engagements your posts received | Organic | `ENGAGEMENTS` | | Engagements | The total number of engagements on your posts published during the reporting period Engagements = Clicks + Reactions + Comments + Reposts | Organic | `ENGAGEMENTS_BY_POST` | | Followers - Growth Rate | The percentage your total followers increased by during the reporting period. Follower Growth Rate = (Current Period - Previous Period) / Previous Period x 100% | | `FOLLOWER_GROWTH_RATE` | | Impressions - All Posts | The number of times your posts have been viewed during the reporting period | Organic | `IMPRESSIONS_ALL_POSTS` | | Impressions | The number of times your posts published during the reporting period have been viewed | Organic | `IMPRESSIONS_BY_POST` | | Followers - Net New | The net new number of LinkedIn members who have followed your Page during the Reporting Period | | `NET_NEW_FOLLOWERS` | | Number of Posts | The number of posts you've published during the reporting period | Organic | `NUMBER_OF_POSTS` | | Page Views - All Posts | The number of times your Page was viewed during the reporting period | | `PAGE_VIEWS_ALL_POSTS` | | Reactions - All Posts | The number of reactions any of your posts received during the reporting period | Organic | `REACTIONS_ALL_POSTS` | | Reactions | The total number of reactions on your posts published during the reporting period | Organic | `REACTIONS_BY_POST` | | Shares - All Posts | The number of times any of your posts were shared during the reporting period | Organic | `SHARES_ALL_POSTS` | | Shares | The number of times your posts published during the reporting period were shared | Organic | `SHARES_BY_POST` | | Followers | The total number of followers you have on this channel | | `TOTAL_FOLLOWERS` | | 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` | | Unique Impressions | The number of times any of your posts were shown to unique LinkedIn members. Similar to Reach | Organic | `UNIQUE_IMPRESSIONS_ALL_POSTS` | | Unique Visitors - All Posts | The number of unique LinkedIn members who visited your Page during the reporting period | Organic | `UNIQUE_VISITORS_ALL_POSTS` | | Video Views | The number of times your videos published during the reporting period were viewed | Organic | `VIDEO_VIEWS_BY_POST` | | Watch Time | The total amount of time viewers spent watching your videos published during the Reporting Period | Organic | `WATCH_TIME_BY_POST` | ## Next steps With your time-series data, you can: * **Build trend dashboards** - Import data into Power BI, Tableau, or Looker to visualize performance over time * **Spot patterns** - See which days or months drive the most engagement to inform your posting strategy * **Compare time periods** - Use `context_start_date` and `context_end_date` to benchmark performance against past results * **Track multiple metrics** - Request several metrics in one call to see relationships between reach, views, and engagement **Related guides:** * [Get Top-Performing Posts with Content Report →](/guides/get-top-performing-posts-with-content-report) - Surface your best content by metric * [Aggregate Cross-Channel Metrics →](/guides/aggregate-cross-channel-metrics) - Get totals instead of time breakdowns * [View the Full API Reference →](https://developers.dashsocial.com/reference/get_reports-data) # Pull total social metrics across channels Source: https://developer.dashsocial.com/guides/reporting/export-dashboard-report-data-via-api/owned-report/pull-total-social-metrics-across-channels Retrieve aggregated KPIs across all connected social channels for executive dashboards and BI reports. Pull aggregated KPIs like impressions, followers, and reach across all connected channels. Use this to populate BI dashboards or build high-level performance reports. *** ## Use cases Building executive dashboards manually takes hours. Metric reports pull totals across all channels in seconds. Build weekly performance reports in Looker showing Instagram follower growth and reach across all brands Export Q4 engagement totals for every brand to present performance trends to leadership Compare your TikTok views against Instagram reach to identify which platform drives more brand awareness *** ## Before you start Make sure you have: * **API access token** with permissions to the relevant brand. * **Brand ID** for the account you want to query. See [API Quickstart](/guides/get-started/quickstart) for more details. **Supported platforms** This report supports these channels: * Instagram (including Stories) * TikTok * Facebook * YouTube * Pinterest * Twitter (X) * LinkedIn **About metric reports** Metric reports return aggregated totals. You get one summary number per metric (like total followers or total reach). No breakdown by day, week, or individual post. Perfect for headline KPIs on executive dashboards. **Test in the UI first:** Create a Dashboard in the Dash Social UI and configure your report there. This previews the metrics and validates your filters before writing code. *** ## Implementation ### Step 1: Map your parameters **Deprecation notice:** The `SINGLE_METRIC` report type is being sunset and will be replaced by `TOTAL_METRIC`. Update your integrations to use `TOTAL_METRIC` to avoid future breaking changes. 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` Social platforms to include: * Instagram: `INSTAGRAM` * Instagram Stories: `INSTAGRAM_STORIES` * TikTok: `TIKTOK` * Facebook: `FACEBOOK` * YouTube: `YOUTUBE` * Pinterest: `PINTEREST` * Twitter (X): `TWITTER` * LinkedIn: `LINKEDIN`
`metrics` Metrics to return (e.g., views, followers, engagements)
`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 if no comparison needed
`report_type` Set to `TOTAL_METRIC` for aggregated totals
`aggregate_by` Primary grouping dimension for the response. Use when querying multiple brands or channels (e.g., `BRAND`). See [accepted values](/changelog/reports-data-response-structured-by-aggregate-by-and-secondary-aggregate-by).
`secondary_aggregate_by` Optional second grouping dimension. Set to `CHANNEL` to break down each brand by channel. When included, the response adds a `breakdowns` level inside each primary group. See [Querying multiple brands and channels](#querying-multiple-brands-and-channels).
*** ### Step 2: Make the API call Send a GET request using the parameters from Step 1. This example pulls views and total followers for brand `144` on Instagram from May 1-7, with April 1-7 as the comparison period. ```http theme={null} GET 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=VIEWS,TOTAL_FOLLOWERS &report_type=TOTAL_METRIC ``` #### Key query parameters * `brand_ids`: Brand(s) to report on. Separate multiple IDs with commas (e.g., `144,145,146`) * `channels`: Social platforms to include. Use the API names from Step 1. Request multiple channels in one call by separating them with commas * `metrics`: Metrics you want totals for. Common options: views, followers, engagements, reach, impressions. See the [full API reference](https://developers.dashsocial.com/reference/get_reports-data) for the complete list with API key names * `report_type`: Set to `TOTAL_METRIC` * `start_date` / `end_date`: Reporting period in `YYYY-MM-DD` format * `context_start_date` / `context_end_date`: Comparison period for trend analysis. Use same dates if comparison isn't needed. Otherwise, choose an earlier period of the same length ### Multiple metrics Request multiple metrics in a single call by separating them with commas (e.g., `VIEWS,TOTAL_FOLLOWERS,TOTAL_ENGAGEMENTS`). **Date format matters:** Always use `YYYY-MM-DD` format for dates (e.g., `2025-05-01`). Other formats will cause errors. **Common errors:** * **400 error** - Check that dates are in `YYYY-MM-DD` format, metrics are valid for your channels, and brand\_id exists * **Invalid date format** - Use `YYYY-MM-DD` format. `2025-05-01` works, `05/01/2025` doesn't * **Missing brand ID** - Verify your brand ID is correct. Get it from your account settings #### Sample response The API returns totals for each metric, organized by brand and channel. The `value` field shows your reporting period total. The `context` field shows your comparison period total. ```json theme={null} { "data": { "144": { "avatar": "https://cdn.dashhudson.com/avatars/2306810931.jpeg", "data_type": "BRAND", "name": "sunny.today", "user_has_access": true, "permissions": { "brand": { "can_access_metric": true }, "user": { "can_access_brand": true } }, "breakdowns": { "INSTAGRAM": { "data_type": "CHANNEL", "name": "Instagram", "metrics": { "TOTAL_FOLLOWERS": { "INSTAGRAM": { "value": 67.0, "context": 68.0, "context_change": -0.014705882352941176 } }, "VIEWS": { "INSTAGRAM": { "value": 291.0, "context": 263.0, "context_change": 0.10646387832699619 } } } } } }, "metrics": { "TOTAL_FOLLOWERS": { "INSTAGRAM": { "value": 67.0, "context": 68.0, "context_change": -0.014705882352941176 } }, "VIEWS": { "INSTAGRAM": { "value": 291.0, "context": 263.0, "context_change": 0.10646387832699619 } } } }, "product_category": "OWNED" } ``` **Understanding the response:** Metrics are organized by brand ID and channel. Brand `144` ("sunny.today") had 67 total followers on Instagram during May 1-7 (down from 68 during April 1-7) and received 408 views (up from 270 in April). *** ### Querying multiple brands and channels When you query multiple brands across multiple channels, add `aggregate_by=BRAND` and `secondary_aggregate_by=CHANNEL` to control how the response is grouped. Without these parameters, the grouping depends on the report type and request context, which may not match what you expect. ```http theme={null} GET https://dashboard.dashsocial.com/reports/data ?channels=INSTAGRAM,FACEBOOK &brand_ids=144,4688 &start_date=2026-05-01 &end_date=2026-05-07 &context_start_date=2026-04-01 &context_end_date=2026-04-07 &metrics=TOTAL_ENGAGEMENTS,TOTAL_FOLLOWERS &report_type=TOTAL_METRIC &aggregate_by=BRAND &secondary_aggregate_by=CHANNEL ``` The response nests channel data under a `breakdowns` key inside each brand: ```json theme={null} { "data": { "144": { "avatar": "https://cdn.dashhudson.com/avatars/2306810931.jpeg", "breakdowns": { "INSTAGRAM": { "data_type": "CHANNEL", "metrics": { "TOTAL_FOLLOWERS": { "INSTAGRAM": { "context": 68.0, "context_change": -0.014705882352941176, "value": 67.0 } }, "VIEWS": { "INSTAGRAM": { "context": 263.0, "context_change": 0.10646387832699619, "value": 291.0 } } }, "name": "Instagram" } }, "data_type": "BRAND", "name": "sunny.today", "permissions": { "brand": { "can_access_metric": true }, "user": { "can_access_brand": true } }, "user_has_access": true }, "metrics": { "TOTAL_FOLLOWERS": { "ALL_CHANNELS": { "context": 68.0, "context_change": -0.014705882352941176, "value": 67.0 } }, "VIEWS": { "ALL_CHANNELS": { "context": 263.0, "context_change": 0.10646387832699619, "value": 291.0 } } } }, "product_category": "OWNED" } ``` Read metrics from each entry using the path `data..breakdowns..metrics..`. The top-level `metrics` object contains totals across all brands and channels. *** ## Metrics **Some metrics require a connected Ads account.** If a request returns `no_ad_account_matching_report_channels`, one or more of the requested metrics depends on Ads data that the brand has not connected. On Facebook and TikTok, metrics labelled "Organic only" or "Promoted only" require a connected Ads account. Combined "Total (Organic + Promoted)" metrics and account-level metrics do not. On Instagram, metrics representing "Total (Organic + Promoted)" performance require a connected Meta Ads account. | Metric Name | Description | Post Types | Metric API Name | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------------------------------------------ | | Accounts Engaged | The number of accounts that have interacted with your organic and promoted posts during the reporting period | | `ACCOUNTS_ENGAGED` | | Accounts Reached | The number of unique accounts that have seen your content. Estimated by Instagram. This total may not equal the sum of follower and non-follower reach due to differences in how Instagram samples and estimates the metric. Note: Instagram account-level metrics include Instagram Stories stats. | | `ACCOUNTS_REACHED` | | Accounts Reached (Followers) | The number of unique follower accounts that have seen your content. Estimated by Instagram. Note: Instagram account-level metrics include Instagram Stories stats. | | `ACCOUNTS_REACHED_FOLLOWERS` | | Accounts Reached (Non-Followers) | The number of unique non-follower accounts that have seen your content. Estimated by Instagram. Note: Instagram account-level metrics include Instagram Stories stats. | | `ACCOUNTS_REACHED_NON_FOLLOWERS` | | Ad Engagements - Paid | The total number of ad engagements your promoted posts received | Promoted | `AD_ENGAGEMENTS` | | Avg. Time Watched - Organic | The average time your videos were played during a single viewing | Organic | `AVG_AVG_WATCH_TIME` | | Avg. Effectiveness - Organic | The average percentage of users that saw your posts and engaged with them Avg. Effectiveness = Engagements / Reach | Organic | `AVG_EFFECTIVENESS_ENGAGEMENTS` | | Avg. Engagement Rate (Followers) - Organic | The average percentage of your audience that engaged with your posts published during the Reporting Period. Engagement Rate = Organic Engagements / Followers | Organic | `AVG_ENGAGEMENT_RATE` | | Avg. Engagement Rate (Views) - Organic | The average percentage of your audience that engaged with your posts published during the Reporting Period. Engagement Rate = Organic Engagements / Views | Organic | `AVG_ENGAGEMENT_RATE_VIEWS` | | Avg. Entertainment Score - Organic | The average Entertainment Score of your Reels published during the reporting period. The score is on a scale of 0 to 10 and is based on volume of organic engagements compared to reach. | Organic | `AVG_ENTERTAINMENT_SCORE` | | Avg. Reach - Total | The average number of unique accounts that saw your posts | Organic + Promoted | `AVG_PAID_AND_ORGANIC_REACH` | | Engagement Rate (Impressions) - Paid | The promoted engagement rate on your posts this period | Promoted | `AVG_PAID_ENGAGEMENT_RATE` | | Avg. Reach - Paid | The average number of unique accounts that saw your posts | Promoted | `AVG_PAID_REACH` | | Avg. Reach - Organic | The average number of unique accounts that saw your posts published during the Reporting Period | Organic | `AVG_REACH` | | Avg. Skip Rate - Organic | The average percentage of viewers who skipped your Reels within the first 3 seconds | Organic | `AVG_REELS_SKIP_RATE` | | Book Now Clicks - All Posts | The number of times people tapped the Book Now button on your profile after viewing your posts | | `BOOK_NOW_CLICKS` | | Call Clicks - All Posts | The number of times people tapped the call button on your profile after viewing your posts | | `CALL_CLICKS` | | Clicks - Paid | The total number of clicks on your promoted posts. This can include link clicks, clicks to your profile, and more. | Promoted | `CLICKS` | | Avg. CTR - Paid | The average percentage of times people clicked your promoted posts after seeing them | Promoted | `CLICK_THROUGH_RATE` | | Comments - Total - All Posts | The number of comments your posts received. Note: Instagram account-level metrics include Instagram Stories stats. | Organic + Promoted | `COMMENTS_ACCOUNT_STATS` | | Post Sentiment - Negative | The percentage of posts published during the reporting period with an overall negative comment sentiment | Organic + Promoted | `COMMENT_SENTIMENT_NEGATIVE_RATE` | | Post Sentiment - Negative | The percentage of posts with a negative overall comment sentiment | Organic | `COMMENT_SENTIMENT_NEGATIVE_RATE_ORGANIC` | | Post Sentiment - Negative | The percentage of posts with a negative overall comment sentiment | Promoted | `COMMENT_SENTIMENT_NEGATIVE_RATE_PROMOTED` | | Post Sentiment - Neutral | The percentage of posts published during the reporting period with an overall neutral comment sentiment | Organic + Promoted | `COMMENT_SENTIMENT_NEUTRAL_RATE` | | Post Sentiment - Neutral | The percentage of posts with a neutral overall comment sentiment | Organic | `COMMENT_SENTIMENT_NEUTRAL_RATE_ORGANIC` | | Post Sentiment - Neutral | The percentage of posts with a neutral overall comment sentiment | Promoted | `COMMENT_SENTIMENT_NEUTRAL_RATE_PROMOTED` | | Post Sentiment - Positive | The percentage of posts published during the reporting period with an overall positive comment sentiment | Organic + Promoted | `COMMENT_SENTIMENT_POSITIVE_RATE` | | Post Sentiment - Positive | The percentage of posts with a positive overall comment sentiment | Organic | `COMMENT_SENTIMENT_POSITIVE_RATE_ORGANIC` | | Post Sentiment - Positive | The percentage of posts with a positive overall comment sentiment | Promoted | `COMMENT_SENTIMENT_POSITIVE_RATE_PROMOTED` | | Content Engagements - All Posts | The number of likes, comments, shares, and saves your content received during the reporting period. Note: Instagram account-level metrics include Instagram Stories stats. | | `CONTENT_ENGAGEMENTS` | | Engagement Rate (Views) - All Posts | The percentage of people who engaged with your content after viewing it | | `CONTENT_ENGAGEMENT_RATE_VIEWS` | | Avg. CPC - Paid | The average cost per click on your promoted posts | Promoted | `COST_PER_CLICK` | | Avg. CPM - Paid | The average cost per 1,000 impressions on your promoted posts | Promoted | `COST_PER_MILE` | | Views - Crossposted - Organic | Total views across Instagram and Facebook for content crossposted natively between platforms. For Reels, includes views from crossposting or cross-app recommendations, where Reels appear on Facebook under your Instagram username. | Organic | `CROSSPOSTED_VIEWS` | | Views - Facebook - Organic | The number of views your posts received on Facebook, for content crossposted natively from Instagram. For Reels, also includes views from cross-app recommendations, where Reels appear on Facebook under your Instagram username. | Organic | `FACEBOOK_VIEWS` | | Followers - Lost | The total numbers of users who unfollowed your account during the Reporting Period. \*Lost Followers data is received once per day in the Pacific Timezone. | | `FOLLOWERS_LOST` | | Followers - Growth Rate | The percentage your followers increased by during the Reporting Period. Follower Growth Rate = (New Followers - Old Followers) / Old Followers x 100% | | `FOLLOWER_GROWTH_RATE` | | Follows - Organic | The number of accounts that started following you after viewing your post | Organic | `FOLLOWS` | | LikeShop Clicks - All Posts | The total number of clicks on any LikeShop feed products during the reporting period | | `LIKESHOP_CLICKS` | | LikeShop Clicks | The number of clicks on your LikeShop feed products on posts published during the reporting period | | `LIKESHOP_CLICKS_BY_POST` | | LikeShop Contact Submissions - All Posts | The number of email submissions during the reporting period | | `LIKESHOP_CONTACT_SUBMISSIONS` | | LikeShop CTR - All Posts | The percentage of times people clicked your product links after viewing your post | | `LIKESHOP_CTR` | | LikeShop Posts | The number of posts you've published during the reporting period that include product links. These are the posts visible on your LikeShop. | | `LIKESHOP_POSTS` | | LikeShop Views - All Posts | The number of times your posts were displayed on a person's screen. This includes repeat views. | | `LIKESHOP_VIEWS` | | Likes - Total - All Posts | The number of likes your posts received. Note: Instagram account-level metrics include Instagram Stories stats. | Organic + Promoted | `LIKES_ACCOUNT_STATS` | | Followers - Net New | The net new number of people who have followed your account | | `NET_NEW_FOLLOWERS` | | Number of Posts | The number of posts you've published during the reporting period | Organic + Promoted | `NUMBER_OF_POSTS` | | Number of Posts | The number of posts you've published during the reporting period | Organic | `NUMBER_OF_POSTS_ORGANIC` | | Number of Posts | The number of posts you've published during the reporting period | Promoted | `NUMBER_OF_POSTS_PAID` | | Follower Activity - All Posts | The average times your followers were active during the reporting period. Data from the Instagram API may be delayed by up to 3 days. | | `ONLINE_FOLLOWERS` | | Comments - Organic | The number of comments on your posts published during the reporting period | Organic | `ORGANIC_COMMENTS` | | Likes - Organic | The number of likes received on posts published during the reporting period | Organic | `ORGANIC_LIKES` | | Comments - Paid | The number of comments your posts received | Promoted | `PAID_COMMENTS` | | Cost per ThruPlay - Paid | The average cost per Thruplay for your videos | Promoted | `PAID_COST_PER_THRUPLAY` | | Impressions - Paid | The number of times your posts were viewed or displayed | Promoted | `PAID_IMPRESSIONS` | | Likes - Paid | The number of likes your posts received | Promoted | `PAID_LIKES` | | Saves - Paid | The number of times your posts were saved | Promoted | `PAID_SAVES` | | Shares - Paid | The number of times your promoted posts were shared | Promoted | `PAID_SHARES_BY_POST` | | Engagements - Paid | The total number of engagements your promoted posts received | Promoted | `PAID_TOTAL_ENGAGEMENTS` | | Video Views - Paid | The number of times your videos were viewed | Promoted | `PAID_VIDEO_VIEWS` | | Profile Clicks - Organic | The number of actions people take when they visit your profile after viewing your post. This can include bio link clicks, calls, emails, and more. | Organic | `PROFILE_CLICKS` | | Profile Bio Link Clicks | The number of times people clicked the link in your profile bio after viewing your post | Organic | `PROFILE_CLICKS_BIO` | | Profile Call Clicks - Organic | The number of times people tapped the call button on your profile after viewing your posts | Organic | `PROFILE_CLICKS_CALL` | | Profile Directions Clicks - Organic | The number of times people clicked to get directions from your profile after viewing your posts | Organic | `PROFILE_CLICKS_DIRECTIONS` | | Profile Email Clicks | The number of times people tapped the email button on your profile after viewing your posts | Organic | `PROFILE_CLICKS_EMAIL` | | Profile Other Clicks - Organic | The number of times people clicked other profile buttons after viewing your posts | Organic | `PROFILE_CLICKS_OTHER` | | Profile Text Clicks | The number of times people tapped the text message button on your profile after viewing your posts | Organic | `PROFILE_CLICKS_TEXT` | | Profile Views | The amount of times your profile has been viewed during the Reporting Period | | `PROFILE_VIEWS` | | Profile Visits - Organic | The number of times your profile was visited after viewing your post | Organic | `PROFILE_VISITS` | | Reposts - Organic | The number of times your posts have been reposted | Organic | `REPOSTS` | | Reposts - Organic - All Posts | The number of times your posts have been reposted, minus any un-reposts. This metric can be negative if un-reposts exceed reposts. Note: Instagram account-level metrics include Instagram Stories stats. | Organic | `REPOSTS_ACCOUNT_STATS` | | Saves - Organic | The number of times your posts published during the reporting period were saved | Organic | `SAVES` | | Saves - Total - All Posts | The number of times your posts were saved. Note: Instagram account-level metrics include Instagram Stories stats. | Organic + Promoted | `SAVES_ACCOUNT_STATS` | | Shares - Organic | The number of times your posts published were shared during the reporting period | Organic | `SHARES` | | Shares - Total - All Posts | The number of times your posts were shared. Note: Instagram account-level metrics include Instagram Stories stats. | Organic + Promoted | `SHARES_ACCOUNT_STATS` | | Engagements - Total | The total number of engagements from all posts published during the Reporting Period | Organic + Promoted | `SUM_TOTAL_ENGAGEMENTS` | | ThruPlays - Paid | The number of times your videos were watched to completion or for at least 15 seconds | Promoted | `THRUPLAYS` | | Comments - Total | The number of comments your posts received | Organic + Promoted | `TOTAL_COMMENTS` | | Engagements - Organic | The total number of engagements on your posts published during the reporting period Engagements = (Likes + Saves + Comments + Shares) - (Unlikes + Unsaves + Deleted comments) | Organic | `TOTAL_ENGAGEMENTS` | | Followers | The total number of followers you have on this channel | | `TOTAL_FOLLOWERS` | | Likes - Total | The number of likes your posts received | Organic + Promoted | `TOTAL_LIKES` | | Saves - Total | The number of times your posts were saved | Organic + Promoted | `TOTAL_SAVES` | | Shares - Total | The number of times your posts were shared | Organic + Promoted | `TOTAL_SHARES` | | Amount Spent - Paid | The total amount of money you've spent boosting your posts. Due to API delays, recent spend figures may be estimated for up to 48 hours. | Promoted | `TOTAL_SPENT` | | 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` | | Video Plays 100% - Paid | The number of times your videos were played to 100% of their length, including plays that skipped to this point | Promoted | `VIDEO_PLAYS_100` | | Video Plays 25% - Paid | The number of times your videos were played to 25% of their length, including plays that skipped to this point | Promoted | `VIDEO_PLAYS_25` | | Video Plays 50% - Paid | The number of times your videos were played to 50% of their length, including plays that skipped to this point | Promoted | `VIDEO_PLAYS_50` | | Video Plays 75% - Paid | The number of times your videos were played to 75% of their length, including plays that skipped to this point | Promoted | `VIDEO_PLAYS_75` | | Views - Organic | The number of times your posts were displayed on a person's screen. This includes repeat views. | Organic | `VIEWS` | | Views - All Posts | The number of times your posts were viewed or displayed. The sum of follower and non-follower views may not add to the Total due to differences in how Instagram samples and estimates the metric. Note: Instagram account-level metrics include Instagram Stories stats. | | `VIEWS_ALL_ACCOUNT_STATS` | | Views (Followers) - All Posts | The number of times your posts were viewed by your followers during the reporting period. The sum of follower and non-follower views may not add to the Total due to differences in how Instagram samples and estimates the metric. Note: Instagram account-level metrics include Instagram Stories stats. | | `VIEWS_FOLLOWERS_ACCOUNT_STATS` | | Views (Non-Followers) - All Posts | The number of times your posts were viewed by non-followers during the reporting period. The sum of follower and non-follower views may not add to the Total due to differences in how Instagram samples and estimates the metric. Note: Instagram account-level metrics include Instagram Stories stats. | | `VIEWS_NON_FOLLOWERS_ACCOUNT_STATS` | | Total Time Watched - Organic | The sum of the time that all viewers watched your videos for | Organic | `WATCH_TIME` | | Metric Name | Description | Post Types | Metric API Name | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----------------------------------- | | Accounts Reached | The number of unique accounts that have seen your content. Estimated by Instagram. This total may not equal the sum of follower and non-follower reach due to differences in how Instagram samples and estimates the metric. | | `ACCOUNTS_REACHED` | | Accounts Reached (Followers) | The number of unique follower accounts that have seen your content. Estimated by Instagram. | | `ACCOUNTS_REACHED_FOLLOWERS` | | Accounts Reached (Non-Followers) | The number of unique non-follower accounts that have seen your content. Estimated by Instagram. | | `ACCOUNTS_REACHED_NON_FOLLOWERS` | | Avg. Completion Rate | The average percentage of people who viewed the entire story. Completion Rate = (Exits - Views) / Views. This metric is only available for reporting after March 24, 2025. | Organic | `AVG_COMPLETION_RATE_VIEWS` | | Avg. Exit Rate | The percentage of people who exited out of the story. Exit Rate = Exits / Views. This metric is only available for reporting after March 24, 2025. | Organic | `AVG_EXIT_RATE_VIEWS` | | Avg. Reach | The average number of unique accounts that saw your stories published during the Reporting Period. | Organic | `AVG_REACH` | | Comments - All Posts | The number of comments your posts received | | `COMMENTS_ACCOUNT_STATS` | | Content Engagements - All Posts | The number of likes, comments, shares, and saves your content received during the reporting period | | `CONTENT_ENGAGEMENTS` | | Exits | The number of times that a user has swiped out of the story or tapped the X in the upper-right corner of the story frame published during the reporting period. An exit is counted even if it occurred in the last millisecond. | Organic | `EXITS` | | Likes - All Posts | The number of likes your posts received | | `LIKES_ACCOUNT_STATS` | | Number of Story Frames | The number of posts you've published during the reporting period | Organic | `NUMBER_OF_POSTS` | | Replies | The number of times people replied to your Instagram Stories published during the reporting period. Due to API restrictions, replies from accounts in the European Economic Area (EEA) or Japan are not included. For Stories created in the EEA or Japan, replies return a value of 0. | Organic | `REPLIES` | | Saves - All Posts | The number of times your posts were saved | | `SAVES_ACCOUNT_STATS` | | Shares - All Posts | The number of times your posts were shared | | `SHARES_ACCOUNT_STATS` | | Replies - All Posts | The number of replies your story frames received | Organic + Promoted | `STORY_REPLIES` | | Stories Link Clicks | The number of link clicks on the story frames published during during the reporting period. Only links scheduled through Dash are trackable via the platform. | Organic | `SWIPE_UPS` | | Taps Back | The number of people who tapped backwards on your stories published during the reporting period | Organic | `TAPS_BACK` | | Taps Forward | The number of people who tapped forward on your stories published during the reporting period | Organic | `TAPS_FORWARD` | | 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` | | Views | The number of times your story frames published during the reporting period was displayed on a person's screen. This includes repeat views This metric is only available for reporting after March 24, 2025. | Organic | `VIEWS` | | Views - All Posts | The number of times your posts were viewed or displayed. The sum of follower and non-follower views may not add to the Total due to differences in how Instagram samples and estimates the metric. | | `VIEWS_ALL_ACCOUNT_STATS` | | Views (Followers) - All Posts | The number of times your posts were viewed by your followers during the reporting period. The sum of follower and non-follower views may not add to the Total due to differences in how Instagram samples and estimates the metric. | | `VIEWS_FOLLOWERS_ACCOUNT_STATS` | | Views (Non-Followers) - All Posts | The number of times your posts were viewed by non-followers during the reporting period. The sum of follower and non-follower views may not add to the Total due to differences in how Instagram samples and estimates the metric. | | `VIEWS_NON_FOLLOWERS_ACCOUNT_STATS` | | Metric Name | Description | Post Types | Metric API Name | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------------------------------------------ | | Avg. Completion Rate - Total | The average percentage of viewers that watched each organic and promoted video published during the reporting period to completion | Organic + Promoted | `AVG_COMPLETION_RATE` | | Avg. Engagement Rate (Reach) - Total | The average Engagement Rate of your organic and promoted videos published during the reporting period. Engagement Rate = Total Engagements / Reach | Organic + Promoted | `AVG_ENGAGEMENT_RATE` | | Avg. Entertainment Score - Total | The average Entertainment Score of your organic and promoted videos during the reporting period. The score is on a scale of 0 to 10 and takes the engagement and retention rate of each video into account. Scores are generated 48 hours after publishing. | Organic + Promoted | `AVG_ENTERTAINMENT_SCORE` | | Avg. FYP Views - Total | The average percentage of views that came from the For You page for organic and promoted videos published during the reporting period | Organic + Promoted | `AVG_FYP_VIEWS` | | Avg. Likes - Organic | The average number of likes your organic posts received. Important: This metric stops updating when ad promotions end. | Organic | `AVG_ORGANIC_LIKES` | | Avg. Reach - Est. Organic | The estimated number of people who watched your video at least once through organic reach. If not all Ad accounts are connected, organic reach may be underreported. Important: This metric stops updating when ad promotions end. Due to API limitations, the sum of organic + promoted Reach may not match the Reach metric once the promotions stop. | ESTIMATED\_ORGANIC | `AVG_ORGANIC_REACH` | | Avg. Shares - Organic | The average number of times your organic posts were shared. Important: This metric stops updating when ad promotions end. | Organic | `AVG_ORGANIC_SHARES` | | Avg. Video Views - Est. Organic | The estimated average number of times viewers watched your video through organic reach. Includes replays and multiple views from the same viewer. Important: This metric stops updating when ad promotions end. Due to API limitations, this is an estimated value and the sum of organic + promoted views may not match the Video Views metric once the promotions end. | ESTIMATED\_ORGANIC | `AVG_ORGANIC_VIDEO_VIEWS` | | Avg. Engagement Rate (Reach) - Paid | The percentage of people who engaged with your promoted posts after seeing them. Important: This metric stops updating when ad promotions end. | Promoted | `AVG_PAID_ENGAGEMENT_RATE` | | Avg. Likes - Paid | The average number of likes your promoted posts received. Important: This metric stops updating when ad promotions end. | Promoted | `AVG_PAID_LIKES` | | Avg. Reach - Paid | The estimated number of people who watched your video at least once through promoted reach. Important: This metric stops updating when ad promotions end. Due to API limitations, the sum of organic + promoted Reach may not match the Reach metric once the promotions stop. | Promoted | `AVG_PAID_REACH` | | Avg. Shares - Paid | The average number of times your promoted posts were shared. Important: This metric stops updating when ad promotions end. | Promoted | `AVG_PAID_SHARES` | | Avg. Video Views - Paid | The estimated average number of times viewers watched your video through promoted reach. Includes replays and multiple views from the same viewer. Important: This metric stops updating when ad promotions end. Due to API limitations, this is an estimated value and the sum of organic + promoted views may not match the Video Views metric once the promotions end. | Promoted | `AVG_PAID_VIDEO_VIEWS` | | Avg. Reach - Total | The average Reach of your organic and promoted videos published during the reporting period | Organic + Promoted | `AVG_REACH` | | Avg. Retention Rate - Total | The average Retention Rate of the organic and promoted videos published during the reporting period | Organic + Promoted | `AVG_RETENTION_RATE` | | Avg. Time Watched - Total | The average amount of time viewers spent watching your organic and promoted videos published during the reporting period | Organic + Promoted | `AVG_TIME_WATCHED` | | Avg. Comments - Total | The average number of comments your organic and promoted videos published during the reporting period received | Organic + Promoted | `AVG_TOTAL_COMMENTS` | | Avg. Engagements - Total | The average number of engagements your organic and promoted videos published during the reporting period received. Total Engagements = Likes + Comments + Shares | Organic + Promoted | `AVG_TOTAL_ENGAGEMENTS` | | Avg. Likes - Total | The average number of likes your organic and promoted videos published during the reporting period received | Organic + Promoted | `AVG_TOTAL_LIKES` | | Avg. Shares - Total | The average number of shares your organic and promoted videos published during the reporting period received | Organic + Promoted | `AVG_TOTAL_SHARES` | | Avg. Traffic - Following Page - Total | The average percentage of video views coming from the Following Page for videos published during the reporting period | Organic + Promoted | `AVG_TRAFFIC_FROM_FOLLOWING_PAGE` | | Avg. Traffic - Hashtag - Total | The average percentage of video views coming from a Hashtag for videos published during the reporting period | Organic + Promoted | `AVG_TRAFFIC_FROM_HASHTAG` | | Avg. Traffic - Personal Profile - Total | The average percentage of video views coming from your Personal profile for videos published during the reporting period | Organic + Promoted | `AVG_TRAFFIC_FROM_PERSONAL_PROFILE` | | Avg. Traffic - Search - Total | The average percentage of video views coming from Search for videos published during the reporting period | Organic + Promoted | `AVG_TRAFFIC_FROM_SEARCH` | | Avg. Traffic - Sound - Total | The average percentage of video views coming from a Sound for videos published during the reporting period | Organic + Promoted | `AVG_TRAFFIC_FROM_SOUND` | | Avg. Video Duration - Total | The average duration of your organic and promoted videos published during the reporting period | Organic + Promoted | `AVG_VIDEO_DURATION` | | Avg. Video Views - Total | The average number of times your organic and promoted videos published during the reporting period were viewed | Organic + Promoted | `AVG_VIDEO_VIEWS` | | Post Sentiment - Negative - Total | The percentage of posts published during the reporting period with an overall negative comment sentiment | Organic + Promoted | `COMMENT_SENTIMENT_NEGATIVE_RATE` | | Post Sentiment - Negative - Organic | The percentage of posts with a negative overall comment sentiment | Organic | `COMMENT_SENTIMENT_NEGATIVE_RATE_ORGANIC` | | Post Sentiment - Negative - Paid | The percentage of posts with a negative overall comment sentiment | Promoted | `COMMENT_SENTIMENT_NEGATIVE_RATE_PROMOTED` | | Post Sentiment - Neutral - Total | The percentage of posts published during the reporting period with an overall neutral comment sentiment | Organic + Promoted | `COMMENT_SENTIMENT_NEUTRAL_RATE` | | Post Sentiment - Neutral - Organic | The percentage of posts with a neutral overall comment sentiment | Organic | `COMMENT_SENTIMENT_NEUTRAL_RATE_ORGANIC` | | Post Sentiment - Neutral - Paid | The percentage of posts with a neutral overall comment sentiment | Promoted | `COMMENT_SENTIMENT_NEUTRAL_RATE_PROMOTED` | | Post Sentiment - Positive - Total | The percentage of posts published during the reporting period with an overall positive comment sentiment | Organic + Promoted | `COMMENT_SENTIMENT_POSITIVE_RATE` | | Post Sentiment - Positive - Organic | The percentage of posts with a positive overall comment sentiment | Organic | `COMMENT_SENTIMENT_POSITIVE_RATE_ORGANIC` | | Post Sentiment - Positive - Paid | The percentage of posts with a positive overall comment sentiment | Promoted | `COMMENT_SENTIMENT_POSITIVE_RATE_PROMOTED` | | Engagements - Total - All Posts | The total number of engagements any of your organic and promoted videos received during the reporting period.Total Engagements = Likes + Comments + Shares | Organic + Promoted | `ENGAGEMENTS` | | Followers - Growth Rate | The percentage your total followers increased by during the reporting period. Follower Growth Rate = (Current Period - Previous Period) / Previous Period x 100% | | `FOLLOWER_GROWTH_RATE` | | LikeShop Clicks - All Posts | The number of clicks on your products on your LikeShop feed | | `LIKESHOP_CLICKS` | | LikeShop Clicks | The number of clicks on your products on your LikeShop feed | | `LIKESHOP_CLICKS_BY_POST` | | LikeShop Contact Submissions - All Posts | The number of email submissions during the reporting period | | `LIKESHOP_CONTACT_SUBMISSIONS` | | LikeShop CTR - All Posts | The percentage of times people clicked your product links after viewing your post | | `LIKESHOP_CTR` | | LikeShop Posts | The number of posts you've published during the reporting period that include product links. These are the posts visible on your LikeShop. | | `LIKESHOP_POSTS` | | LikeShop Views - All Posts | The number of times your posts were displayed on a person's screen. This includes repeat views. | | `LIKESHOP_VIEWS` | | Followers - Net New | The net new number of people who have followed your account during the reporting period | | `NET_NEW_FOLLOWERS` | | Number of Posts - Organic | The number of organic posts you've published during the reporting period | Organic | `NUMBER_OF_ORGANIC_POSTS` | | Number of Posts - Paid | The number of promoted posts you've published during the reporting period | Promoted | `NUMBER_OF_PAID_POSTS` | | Number of Posts - Total | The number of posts you've published during the reporting period | Organic + Promoted | `NUMBER_OF_POSTS` | | Comments - Total - All Posts | The number of comments any of your organic and promoted videos received during the reporting period | Organic + Promoted | `ORGANIC_COMMENTS` | | Likes - Total - All Posts | The number of likes any of your organic and promoted videos received during the reporting period | Organic + Promoted | `ORGANIC_LIKES` | | Likes - Organic | The number of likes your organic posts received. Important: This metric stops updating when ad promotions end. | Organic | `ORGANIC_LIKES_POSTS` | | Shares - Organic | The number of times your organic posts were shared. Important: This metric stops updating when ad promotions end. | Organic | `ORGANIC_SHARES` | | Video Views - Est. Organic | The estimated number of times viewers watched your video through organic reach. Includes replays and multiple views from the same viewer. Important: This metric stops updating when ad promotions end. Due to API limitations, this is an estimated value and the sum of organic + promoted views may not match the Video Views metric once the promotions end. | ESTIMATED\_ORGANIC | `ORGANIC_VIEWS` | | Engagements - Paid | The total number of engagements your promoted posts received. Important: This metric stops updating when ad promotions end. | Promoted | `PAID_ENGAGEMENTS` | | Likes - Paid | The number of likes your promoted posts received. Important: This metric stops updating when ad promotions end. | Promoted | `PAID_LIKES` | | Shares - Paid | The number of times your promoted posts were shared. Important: This metric stops updating when ad promotions end. | Promoted | `PAID_SHARES` | | Video Views - Paid | The estimated number of times viewers watched your video through promoted reach. Includes replays and multiple views from the same viewer. Important: This metric stops updating when ad promotions end. Due to API limitations, this is an estimated value and the sum of organic + promoted views may not match the Video Views metric once the promotions end. | Promoted | `PAID_VIDEO_VIEWS` | | Avg. Engagement Rate (Views) - Paid | The percentage of people who engaged with your promoted posts after seeing them. Important: This metric stops updating when ad promotions end. | Promoted | `PAID_VIEWS_BASED_ENGAGEMENT_RATE` | | Profile Views | The number of times people viewed your profile | | `PROFILE_VIEWS` | | Shares - Total - All Posts | The number of times any of your organic and promoted videos were shared during the reporting period | Organic + Promoted | `SHARES` | | Comments - Total | The number of comments your organic and promoted videos published during the reporting period received | Organic + Promoted | `TOTAL_COMMENTS` | | Engagements - Total | The number of engagements your organic and promoted videos published during the reporting period received Total Engagements = Likes + Comments + Shares | Organic + Promoted | `TOTAL_ENGAGEMENTS` | | Favorites - Total | The total number of times your posts have been added to favorites | Organic + Promoted | `TOTAL_FAVORITES` | | Followers | The total number of followers you have on this channel | | `TOTAL_FOLLOWERS` | | Follows - Total | The number of viewers who started following you after viewing your posts | Organic + Promoted | `TOTAL_FOLLOWS` | | Likes - Total | The number of likes your organic and promoted videos published during the reporting period received | Organic + Promoted | `TOTAL_LIKES` | | Follows - Organic | The number of viewers who started following you after viewing your posts. Important: This metric stops updating when ad promotions end. | Organic | `TOTAL_ORGANIC_FOLLOWS` | | Profile Views - Organic | The number of profile views generated by your posts. Important: This metric stops updating when ad promotions end. Data may be delayed by 48 hours. | Organic | `TOTAL_ORGANIC_PROFILE_VIEWS` | | Follows - Paid | The number of viewers who started following you after viewing your posts. Important: This metric stops updating when ad promotions end. | Promoted | `TOTAL_PAID_FOLLOWS` | | Profile Views - Paid | The number of profile views generated by your posts. Important: This metric stops updating when ad promotions end. Data may be delayed by 48 hours. | Promoted | `TOTAL_PAID_PROFILE_VIEWS` | | Profile Views - Total | The total number of profile views generated by your posts. Data may be delayed by 48 hours. | Organic + Promoted | `TOTAL_PROFILE_VIEWS` | | Shares - Total | The number of times your posts published during the reporting period were shared | Organic + Promoted | `TOTAL_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` | | Video Duration - Total | The length of your published videos | Organic + Promoted | `TOTAL_VIDEO_DURATION` | | Video Views - Total | The number of times your organic and promoted videos published during the reporting period were viewed | Organic + Promoted | `TOTAL_VIDEO_VIEWS` | | Video Views - Total - All Posts | The number of times any of your organic and promoted videos were viewed during the reporting period | Organic + Promoted | `VIDEO_VIEWS` | | Avg. Engagement Rate (Views) - Total | The percentage of people who engaged with your posts after seeing them | Organic + Promoted | `VIEWS_BASED_ENGAGEMENT_RATE` | | Total Time Watched - Total | The total amount of time viewers spent watching your videos | Organic + Promoted | `WATCH_TIME` | | Metric Name | Description | Post Types | Metric API Name | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------------------------------------------ | | Avg. Effectiveness - Total | The average percentage of viewers who saw your posts and engaged with them | Organic + Promoted | `AVG_EFFECTIVENESS_V2` | | Avg. Engagement Rate - Total | The average percentage of people who engaged with a post after seeing it | Organic + Promoted | `AVG_ENGAGEMENT_RATE_V2` | | Avg. Effectiveness - Organic | The average percentage of viewers who saw your posts and engaged with them. Organic Effectiveness is not available for Promoted posts published after June 15, 2026 | Organic | `AVG_ORGANIC_EFFECTIVENESS_V2` | | Avg. Engagement Rate - Organic | The average percentage of people who engaged with a post after seeing it | Organic | `AVG_ORGANIC_ENGAGEMENT_RATE_V2` | | Avg. Viewers - Total | The average number of unique accounts that have viewed your posts at least once. Note: Values before July 31, 2025 reflect Reach, which Meta replaced with Viewers. | Organic + Promoted | `AVG_PAID_AND_ORGANIC_POST_REACH_V2` | | Avg. Effectiveness - Paid | The average percentage of viewers who saw your posts and engaged with them | Promoted | `AVG_PAID_EFFECTIVENESS_V2` | | Avg. Engagement Rate - Paid | The average percentage of people who engaged with a post after seeing it | Promoted | `AVG_PAID_ENGAGEMENT_RATE_V2` | | Avg. Reach - Paid | The average number of unique accounts that have viewed your posts at least once. Note: This metric uses Reach from Ad campaigns. | Promoted | `AVG_PAID_POST_REACH_V2` | | Avg. CTR - Paid | The average percentage of times people clicked your posts after seeing them | Promoted | `CLICK_THROUGH_RATE` | | Comments - Total - All Posts | The number of comments any of your posts received during the Reporting Period | Organic + Promoted | `COMMENTS_ALL_POSTS` | | Post Sentiment - Negative | The percentage of posts published during the Reporting Period with an overall negative comment sentiment | Organic + Promoted | `COMMENT_SENTIMENT_NEGATIVE_RATE` | | Post Sentiment - Negative | The percentage of posts with a negative overall comment sentiment | Organic | `COMMENT_SENTIMENT_NEGATIVE_RATE_ORGANIC` | | Post Sentiment - Negative | The percentage of posts with a negative overall comment sentiment | Promoted | `COMMENT_SENTIMENT_NEGATIVE_RATE_PROMOTED` | | Post Sentiment - Neutral | The percentage of posts published during the Reporting Period with an overall neutral comment sentiment | Organic + Promoted | `COMMENT_SENTIMENT_NEUTRAL_RATE` | | Post Sentiment - Neutral | The percentage of posts with a neutral overall comment sentiment | Organic | `COMMENT_SENTIMENT_NEUTRAL_RATE_ORGANIC` | | Post Sentiment - Neutral | The percentage of posts with a neutral overall comment sentiment | Promoted | `COMMENT_SENTIMENT_NEUTRAL_RATE_PROMOTED` | | Post Sentiment - Positive | The percentage of posts published during the Reporting Period with an overall positive comment sentiment | Organic + Promoted | `COMMENT_SENTIMENT_POSITIVE_RATE` | | Post Sentiment - Positive | The percentage of posts with a positive overall comment sentiment | Organic | `COMMENT_SENTIMENT_POSITIVE_RATE_ORGANIC` | | Post Sentiment - Positive | The percentage of posts with a positive overall comment sentiment | Promoted | `COMMENT_SENTIMENT_POSITIVE_RATE_PROMOTED` | | Avg. CPC - Paid | The average cost per click on your posts | Promoted | `COST_PER_CLICK` | | Avg. CPM - Paid | The average cost per 1,000 impressions on your posts | Promoted | `COST_PER_MILE` | | Followers - Growth Rate | The percentage your Page's Followers increased by during the Reporting Period. Followers Growth Rate = (New Followers - Old Followers) / Old Followers x 100% | | `FOLLOWER_GROWTH_RATE` | | Link Clicks - Total | The number of times people clicked on the link in a post or link preview for posts published during the Reporting Period | Organic + Promoted | `LINK_CLICKS` | | Followers - Net New | The net new number of Followers your page has gained | | `NET_NEW_FOLLOWERS` | | Number of Posts | The number of posts you've published during the reporting period | Organic + Promoted | `NUMBER_OF_POSTS` | | Number of Posts | The number of posts you've published during the reporting period | Promoted | `NUMBER_OF_POSTS_PAID` | | Comments - Organic | The number of comments received on posts published during the reporting period | Organic | `ORGANIC_COMMENTS` | | Engagements - Organic | The total number of engagements your posts received | Organic | `ORGANIC_ENGAGEMENTS_POSTS_V2` | | Number of Posts | The number of posts you've published during the reporting period | Organic | `ORGANIC_NUMBER_OF_POSTS` | | Reactions - Organic | The total number of reactions your posts published during the reporting period received | Organic | `ORGANIC_REACTIONS` | | Shares - Organic | The number of times your posts published during the reporting period were shared | Organic | `ORGANIC_SHARES` | | Video Views - Organic | The number of times your videos were viewed | Organic | `ORGANIC_VIDEO_VIEWS` | | Views - Organic | The number of times your posts were viewed | Organic | `ORGANIC_VIEWS_BY_POST` | | Other Clicks - Total | The number of clicks on your posts, including links and other clickable elements on posts published during the reporting period | Organic + Promoted | `OTHER_CLICKS` | | Views - Organic - All Posts | The number of times your posts were viewed or displayed during the reporting period | Organic | `PAGE_VIEWS_ORGANIC` | | Views - Paid - All Posts | The number of times your posts were viewed or displayed during the reporting period | Promoted | `PAGE_VIEWS_PAID` | | Views - Total - All Posts | The number of times your posts were viewed or displayed during the reporting period | Organic + Promoted | `PAGE_VIEWS_PAID_AND_ORGANIC` | | Video Complete Views - Total | The number of times your video was played from the beginning to 95% or more of its length | Organic + Promoted | `PAID_AND_ORGANIC_VIDEO_COMPLETE_VIEWS` | | Video Views - Total | The number of times your videos were viewed | Organic + Promoted | `PAID_AND_ORGANIC_VIDEO_VIEWS` | | Views - Total | The number of times your posts were viewed | Organic + Promoted | `PAID_AND_ORGANIC_VIEWS_BY_POST` | | Comments - Paid | The number of comments your posts received | Promoted | `PAID_COMMENTS` | | Avg. Cost Per Thruplay - Paid | The average cost per Thruplay for your videos | Promoted | `PAID_COST_PER_THRUPLAY` | | Engagements - Paid | The total number of engagements your posts received | Promoted | `PAID_ENGAGEMENTS_POSTS` | | Avg. Frequency - Paid | The average number of times people saw your promoted posts | Promoted | `PAID_FREQUENCY` | | Reactions - Paid | The number of reactions your posts received. Reactions include Like, Love, Care, Haha, Wow, Sad and Angry. | Promoted | `PAID_REACTIONS` | | Shares - Paid | The number of times your posts were shared | Promoted | `PAID_SHARES` | | ThruPlays - Paid | The number of times your posts were watched to completion or for at least 15 seconds | Promoted | `PAID_THRUPLAYS` | | Video Complete Views - Paid | The number of times your videos were played from the beginning to 95%, or more, of their length | Promoted | `PAID_VIDEO_COMPLETE_VIEWS` | | Video Plays 25% - Paid | The number of times your video was played to 25% of its length, including plays that skipped to this point | Promoted | `PAID_VIDEO_PLAYS_25` | | Video Plays 50% - Paid | The number of times your video was played to 50% of its length, including plays that skipped to this point | Promoted | `PAID_VIDEO_PLAYS_50` | | Video Plays 75% - Paid | The number of times your video was played to 75% of its length, including plays that skipped to this point | Promoted | `PAID_VIDEO_PLAYS_75` | | Video Views - Paid | The number of times your videos were viewed | Promoted | `PAID_VIDEO_VIEWS` | | Views - Paid | The number of times your posts were viewed | Promoted | `PAID_VIEWS_BY_POST` | | Photo View Clicks - Total | The number of times users clicked on your photos published during the reporting period | Organic + Promoted | `PHOTO_VIEW_CLICKS` | | Post Clicks - Total | The number of times a user clicked anywhere on your posts published during the reporting period | Organic + Promoted | `POST_CLICKS` | | Reactions - Total | The number of times people clicked on like, care, love, wow, haha, sad, and anger reactions on posts published during the Reporting Period | Organic + Promoted | `REACTIONS` | | Reactions - Total - All Posts | The number of reactions your posts received. Reactions include Like, Love, Care, Haha, Wow, Sad and Angry. | Organic + Promoted | `REACTIONS_ALL_POSTS` | | Plays - Total | The number of times your videos published during the Reporting Period were initially played. This excludes replays | Organic + Promoted | `REELS_BLUE_REELS_PLAYS_COUNT` | | Replays - Total | The number of rewatches your videos published during the Reporting Period received in the same session | Organic + Promoted | `REELS_FB_REELS_REPLAY_COUNT` | | Avg. Time Watched - Total | The average time your videos published during the Reporting Period were played during a single viewing | Organic + Promoted | `REELS_POST_VIDEO_AVG_TIME_WATCHED` | | Follows - Total | The number of viewers who followed your Page after viewing your videos published during the Reporting Period | Organic + Promoted | `REELS_POST_VIDEO_FOLLOWERS` | | Total Time Watched - Total | The sum of time that viewers watched your videos published during the Reporting Period | Organic + Promoted | `REELS_POST_VIDEO_VIEW_TIME` | | Reactions - Angry - Total | The number of times people used an Angry reaction to your post | Organic + Promoted | `REEL_REACTION_ANGRY` | | Reactions - Haha - Total | The number of times people used a Haha reaction to your post | Organic + Promoted | `REEL_REACTION_HAHA` | | Reactions - Like - Total | The number of times people used a Like or a Care reaction to your post | Organic + Promoted | `REEL_REACTION_LIKE` | | Reactions - Love - Total | The number of times people used a Love reaction to your post | Organic + Promoted | `REEL_REACTION_LOVE` | | Reactions - Sad - Total | The number of times people used a Sad reaction to your post | Organic + Promoted | `REEL_REACTION_SAD` | | Reactions - Wow - Total | The number of times people used a Wow reaction to your post | Organic + Promoted | `REEL_REACTION_WOW` | | Shares - Total | The number of times your posts were shared | Organic + Promoted | `SHARES` | | Comments - Total | The number of comments your posts received | Organic + Promoted | `TOTAL_COMMENTS` | | Engagements - Total - All Posts | The total number of reactions, comments, shares, and post clicks on all posts during the Reporting Period | Organic + Promoted | `TOTAL_ENGAGEMENTS` | | Engagements - Total | The total number of engagements your posts received | Organic + Promoted | `TOTAL_ENGAGEMENTS_POSTS_V2` | | Followers | The total number of Followers your Facebook Page has | | `TOTAL_FOLLOWERS` | | Amount Spent - Paid | The total amount of money you've spent boosting your posts. Due to API delays, recent spend figures may be estimated for up to 48 hours. | Promoted | `TOTAL_SPENT` | | Total Social Impact | 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` | | Video Complete Views - Organic | The number of times your videos published during the Reporting Period were played from the beginning to 95%, or more, of its length | Organic | `VIDEO_COMPLETE_VIEWS` | | Viewers - All Posts | The number of unique accounts that viewed any content on your Page. Content includes reels, posts, stories, live videos and ads. | | `VIEWERS` | | Metric Name | Description | Post Types | Metric API Name | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----------------------------------- | | Avg. Card Click Rate - Total | The average cards click-through-rate on your organic and promoted videos published during the Reporting Period. Card Click Rate = Card Clicks / Card Impressions | Organic + Promoted | `AVG_CARD_CLICK_RATE` | | Avg. Card Teaser Click Rate - Total | The average card teasers click-through-rate on your organic and promoted videos published during the Reporting Period. Card Teaser Click Rate = Card Teaser Clicks / Card Teaser Impressions | Organic + Promoted | `AVG_CARD_TEASER_CLICK_RATE` | | Avg. View Duration - Total - All Posts | The average amount of time viewers spent watching any of your organic and promoted videos during the Reporting Period | Organic + Promoted | `AVG_VIEW_DURATION` | | Avg. Percentage Viewed - Total - All Posts | The average retention rate of your organic and promoted videos during the Reporting Period | Organic + Promoted | `AVG_VIEW_PERCENTAGE` | | Card Clicks - Total - All Posts | The number of times the cards were clicked on all your organic and promoted videos during the Reporting Period | Organic + Promoted | `CARD_CLICKS` | | Avg. Card Click Rate - Total - All Posts | The average cards click-through-rate on all your organic and promoted videos during the Reporting Period. Card Click Rate = Card Clicks / Card Impressions | Organic + Promoted | `CARD_CLICK_RATE` | | Card Impressions - Total - All Posts | The number of times cards were displayed on all your organic and promoted videos during the Reporting Period | Organic + Promoted | `CARD_IMPRESSIONS` | | Card Teaser Clicks - Total - All Posts | The number of times the card teasers were clicked on all your organic and promoted videos during the Reporting Period | Organic + Promoted | `CARD_TEASER_CLICKS` | | Avg. Card Teaser Click Rate - Total - All Posts | The average card teasers click-through-rate on all your organic and promoted videos during the Reporting Period. Card Teaser Click Rate = Card Teaser Clicks / Card Teaser Impressions | Organic + Promoted | `CARD_TEASER_CLICK_RATE` | | Card Teaser Impressions - Total - All Posts | The number of times card teasers were displayed on all your organic and promoted videos during the Reporting Period | Organic + Promoted | `CARD_TEASER_IMPRESSIONS` | | Comments - Total - All Posts | The number of comments any of your organic and promoted videos received during the Reporting Period | Organic + Promoted | `COMMENTS` | | Post Sentiment - Negative | The percentage of posts published during the Reporting Period with an overall negative comment sentiment | Organic + Promoted | `COMMENT_SENTIMENT_NEGATIVE_RATE` | | Post Sentiment - Neutral | The percentage of posts published during the Reporting Period with an overall neutral comment sentiment | Organic + Promoted | `COMMENT_SENTIMENT_NEUTRAL_RATE` | | Post Sentiment - Positive | The percentage of posts published during the Reporting Period with an overall positive comment sentiment | Organic + Promoted | `COMMENT_SENTIMENT_POSITIVE_RATE` | | Dislikes - Total - All Posts | The number of dislikes any of your organic and promoted videos received during the Reporting Period | Organic + Promoted | `DISLIKES` | | Engagements - Total - All Posts | The total number of engagements any of your organic and promoted videos received during the Reporting Period. Total Engagements = Likes + Dislikes + Comments + Shares | Organic + Promoted | `ENGAGEMENTS` | | Premium Watch Time - Total - All Posts | The total amount of time your organic and promoted videos were viewed during the Reporting Period by YouTube Premium members | Organic + Promoted | `ESTIMATED_PREMIUM_SECONDS_WATCHED` | | Watch Time - Total - All Posts | The total amount of time that viewers watched any organic and promoted videos on your channel during the Reporting Period | Organic + Promoted | `ESTIMATED_SECONDS_WATCHED` | | Likes - Total - All Posts | The number of likes any of your organic and promoted videos received during the Reporting Period | Organic + Promoted | `LIKES` | | Number of Posts | The number of posts you've published during the reporting period | Organic + Promoted | `NUMBER_OF_POSTS` | | Premium Views - Total - All Posts | The number of times your organic and promoted videos were viewed during the Reporting Period by YouTube Premium members | Organic + Promoted | `PREMIUM_VIEWS` | | Shares - Total - All Posts | The number of shares any of your organic and promoted videos received during the Reporting Period | Organic + Promoted | `SHARES` | | Subscribers - Lost | The total number of people who unsubscribed from your channel | | `SUBSCRIBERS_LOST` | | Subscribers - Net New | The net new number of users who have subscribed to your channel during the Reporting Period | | `SUBSCRIBERS_NET_NEW` | | Subscribers | The number of users who have subscribed to your channels by the last day of the Reporting Period | | `SUBSCRIBERS_TOTAL` | | Subscribers - Growth Rate | The percentage your subscribers have increased by during the Reporting Period. Subscriber Growth Rate = (Current Period - Previous Period) / Previous Period x 100% | | `SUBSCRIBER_GROWTH_RATE` | | Avg. View Duration - Total | The average amount of time viewers spent watching your organic and promoted videos published during the Reporting Period | Organic + Promoted | `TOTAL_AVG_VIEW_DURATION` | | Avg. Percentage Viewed - Total | The average retention rate of your organic and promoted videos published during the Reporting Period | Organic + Promoted | `TOTAL_AVG_VIEW_PERCENTAGE` | | Card Clicks - Total | The number of times the cards were clicked on your organic and promoted videos published during the Reporting Period | Organic + Promoted | `TOTAL_CARD_CLICKS` | | Card Impressions - Total | The number of times cards were displayed on your organic and promoted videos published during the Reporting Period | Organic + Promoted | `TOTAL_CARD_IMPRESSIONS` | | Card Teaser Clicks - Total | The number of times the card teasers were clicked on your organic and promoted videos published during the Reporting Period | Organic + Promoted | `TOTAL_CARD_TEASER_CLICKS` | | Card Teaser Impressions - Total | The number of times card teasers were displayed on your organic and promoted videos published during the Reporting Period | Organic + Promoted | `TOTAL_CARD_TEASER_IMPRESSIONS` | | Comments - Total | The total number of comments your organic and promoted videos published during the Reporting Period received | Organic + Promoted | `TOTAL_COMMENTS` | | Dislikes - Total | The total number of dislikes your organic and promoted videos published during the Reporting Period received | Organic + Promoted | `TOTAL_DISLIKES` | | Engagements - Total | The total number of engagements your organic and promoted videos published during the Reporting Period received. Total Engagements = Likes + Dislikes + Comments + Shares | Organic + Promoted | `TOTAL_ENGAGEMENTS` | | Watch Time - Total | The total amount of time that viewers watched organic and promoted videos on your channel that were published during the Reporting Period | Organic + Promoted | `TOTAL_ESTIMATED_SECONDS_WATCHED` | | Premium Watch Time - Total | The total amount of time your organic and promoted videos published during the Reporting Period were viewed by YouTube Premium members | Organic + Promoted | `TOTAL_EST_PREMIUM_SECONDS_WATCHED` | | Likes - Total | The total number of likes your organic and promoted videos published during the Reporting Period received | Organic + Promoted | `TOTAL_LIKES` | | Premium Views - Total | The number of times your organic and promoted videos published during the Reporting Period were viewed by YouTube Premium members | Organic + Promoted | `TOTAL_PREMIUM_VIEWS` | | Shares - Total | The total number of shares your organic and promoted videos published during the Reporting Period received | Organic + Promoted | `TOTAL_SHARES` | | Subscribers - Gained | The number of viewers who subscribed while watching your videos | Organic + Promoted | `TOTAL_SUBSCRIBERS_GAINED` | | Subscribers - Lost | The number of viewers who unsubscribed while watching your videos | Organic + Promoted | `TOTAL_SUBSCRIBERS_LOST` | | 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` | | Added to Playlist - Total | The total number of times your organic and promoted videos published during the Reporting Period were added to a playlist | Organic + Promoted | `TOTAL_VIDEOS_ADDED_TO_PLAYLIST` | | Video Views - Total | The total number of times your organic and promoted videos published during the Reporting Period were viewed | Organic + Promoted | `TOTAL_VIDEO_VIEWS` | | Added to Playlist - Total - All Posts | The number of times any of your organic and promoted videos were added to any YouTube playlists during the Reporting Period | Organic + Promoted | `VIDEOS_ADDED_TO_PLAYLIST` | | Video Views - Total - All Posts | The number of times your organic and promoted videos were viewed during the Reporting Period | Organic + Promoted | `VIEWS` | | Metric Name | Description | Post Types | Metric API Name | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | --------------------------- | | Engagement Rate - All Posts | The average percentage of your audience that engaged with your Pins during the Reporting Period. Engagement Rate = (Pin Clicks + Outbound Clicks + Saves) / Impressions. | Organic | `AVG_ENGAGEMENT_RATE` | | Avg. Watch Time | The average time spent watching your video Pins | Organic | `AVG_WATCH_TIME` | | Pin Clicks - All Posts | The number of times your Pins were clicked to view more details during the Reporting Period | Organic | `CLOSEUPS` | | Engagements | The total number of engagements your Pins received | Organic | `ENGAGEMENTS` | | Followers - Growth Rate | The percentage your followers increased by over the comparison period | | `FOLLOWER_GROWTH_RATE` | | Impressions - All Posts | The number of times your Pins were viewed or displayed | Organic | `IMPRESSIONS` | | Outbound Clicks - All Posts | The number of times the links in your Pins were clicked during the Reporting Period | Organic | `LINK_CLICKS` | | Followers - Net New | The net new number of people who have followed your account | | `NET_NEW_FOLLOWERS` | | Number of Posts | The number of posts you've published during the reporting period | Organic | `NUMBER_OF_POSTS` | | Saves - All Posts | The number of times users saved your Pins during the reporting period | Organic | `SAVES` | | Avg. Engagement Rate | The average percentage of your audience that engaged with your Pins published during the reporting period. Engagement Rate = (Pin Clicks + Outbound Clicks + Saves) / Impressions. | Organic | `TOTAL_AVG_ENGAGEMENT_RATE` | | Engagements - All Posts | The total number of organic engagements your images, videos, and product pins received during the reporting period | Organic | `TOTAL_ENGAGEMENTS` | | Followers | The total number of followers you have on this channel | | `TOTAL_FOLLOWERS` | | Impressions | The number of impressions received on posts published during the reporting period | Organic | `TOTAL_IMPRESSIONS` | | Outbound Clicks | The number of clicks on the links in your Pins published during the reporting period | Organic | `TOTAL_LINK_CLICKS` | | Saves | The number of times your Pins published during the reporting period were saved by a user | Organic | `TOTAL_SAVES` | | 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` | | Video Views | The number of views lasting at least two seconds with 50% of the video pin visible from post published during the reporting period | Organic | `TOTAL_VIDEO_VIEWS` | | Metric Name | Description | Post Types | Metric API Name | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | --------------------------------- | | Engagement Rate - All Posts | The average engagement rate of your tweets during the reporting period. Engagement Rate = Total Engagements / Impressions | Organic | `AVG_ENGAGEMENT_RATE` | | Link Clicks | The number of times links on your posts were clicked | Organic | `CLICKS_BY_POST` | | Post Sentiment - Negative | The percentage of posts published during the reporting period with an overall negative comment sentiment | Organic | `COMMENT_SENTIMENT_NEGATIVE_RATE` | | Post Sentiment - Neutral | The percentage of posts published during the reporting period with an overall neutral comment sentiment | Organic | `COMMENT_SENTIMENT_NEUTRAL_RATE` | | Post Sentiment - Positive | The percentage of posts published during the reporting period with an overall positive comment sentiment | Organic | `COMMENT_SENTIMENT_POSITIVE_RATE` | | Followers - Growth Rate | The percentage your followers increased by during the reporting period. Follower Growth Rate = (New Followers - Old Followers) / Old Followers x 100% | | `FOLLOWER_GROWTH_RATE` | | Impressions - All Posts | The number of times your posts were viewed or displayed | Organic | `IMPRESSIONS` | | Impressions | The number of times your posts published during the reporting period were displayed | Organic | `IMPRESSIONS_BY_POST` | | Likes - All Posts | The number of likes your Tweets received during the reporting period | Organic | `LIKES` | | Link Clicks - All Posts | The number of times links on your Tweets were clicked during the reporting period | Organic | `LINK_CLICKS` | | Followers - Net New | The net new number of people who have followed your account | | `NET_NEW_FOLLOWERS` | | Number of Posts | The number of posts you've published during the reporting period | Organic | `NUMBER_OF_POSTS` | | Video Views - All Posts | The number of times your videos were viewed | Organic | `ORGANIC_VIDEO_VIEWS` | | Profile Clicks - All Posts | The number of times your profile has been clicked from Tweets during the reporting period | Organic | `PROFILE_CLICKS` | | Quote Posts - All Posts | The number of times your Tweets were Quote Tweeted during the reporting period | Organic | `QUOTE_TWEETS` | | Replies - All Posts | The number of replies your Tweets received during the reporting period | Organic | `REPLIES` | | Replies | The number of replies your posts received | Organic | `REPLIES_BY_POST` | | Reposts - All Posts | The number of times your Tweets were Retweeted during the reporting period | Organic | `RETWEETS` | | Reposts | The number of times your posts were reposted | Organic | `RETWEETS_BY_POST` | | Avg. Engagement Rate | The average engagement rate of your tweets published during the reporting period. Engagement Rate = Total Engagements / Impressions | Organic | `TOTAL_AVG_ENGAGEMENT_RATE` | | Engagements - All Posts | The total number of times a user interacted with your tweets during the reporting period, including Retweets, replies, likes, hashtags, or link clicks | Organic | `TOTAL_ENGAGEMENTS` | | Engagements | The total number of engagements your posts published during the reporting period received Engagements = Likes + Dislikes + Comments + Shares | Organic | `TOTAL_ENGAGEMENTS_POSTS` | | Followers | The total number of followers you have on this channel | | `TOTAL_FOLLOWERS` | | Likes | The number of likes your posts received | Organic | `TOTAL_LIKES` | | Total Reposts - All Posts | The total number of times your Tweets were Retweeted during the reporting period. Total Retweets = Retweets + Quote Tweets | Organic | `TOTAL_RETWEETS` | | 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` | | Video Views | The number of times your videos were viewed | Organic + Promoted | `TOTAL_VIDEO_VIEWS` | | Metric Name | Description | Post Types | Metric API Name | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | -------------------------------- | | Avg. CTR | The average percentage of your audience that clicked on posts published during the reporting period. Click Through Rate = Clicks / Impressions | Organic | `AVG_CLICK_THROUGH_RATE_BY_POST` | | Avg. Engagements | The total number of engagements your posts received | Organic | `AVG_ENGAGEMENTS_BY_POST` | | Avg. Engagement Rate - All Posts | The average engagement rate of all your posts during the reporting period. Engagement Rate = (Clicks + Reactions + Comments + Reposts) / Impressions | Organic | `AVG_ENGAGEMENT_RATE_ALL_POSTS` | | Avg. Engagement Rate | The average engagement rate of your posts that were published during the Reporting Period. Engagement Rate = (Clicks + Reactions + Comments + Reposts) / Impressions | Organic | `AVG_ENGAGEMENT_RATE_BY_POST` | | Avg. Unique Impressions | The average number of unique LinkedIn members that saw your posts published during the reporting period. Similar to Reach | Organic | `AVG_UNIQUE_IMPRESSIONS_BY_POST` | | Avg. Video Views | The number of times your videos were viewed | Organic | `AVG_VIDEO_VIEWS_BY_POST` | | Clicks - All Posts | The number of times people clicked on any of your posts during the reporting period | Organic | `CLICKS_ALL_POSTS` | | Clicks | The number of times people clicked on your posts published during the reporting period | Organic | `CLICKS_BY_POST` | | Avg. CTR - All Posts | The average percentage of your audience that clicked on your posts during the Reporting Period. Click Through Rate = Clicks / Impressions | Organic | `CLICK_THROUGH_RATE` | | Comments - All Posts | The number of comments any of your posts received during the reporting period | Organic | `COMMENTS_ALL_POSTS` | | Comments | The number of comments received on posts published during the reporting period | Organic | `COMMENTS_BY_POST` | | Engagements - All Posts | The total number of engagements your posts received | Organic | `ENGAGEMENTS` | | Engagements | The total number of engagements on your posts published during the reporting period Engagements = Clicks + Reactions + Comments + Reposts | Organic | `ENGAGEMENTS_BY_POST` | | Followers - Growth Rate | The percentage your total followers increased by during the reporting period. Follower Growth Rate = (Current Period - Previous Period) / Previous Period x 100% | | `FOLLOWER_GROWTH_RATE` | | Impressions - All Posts | The number of times your posts have been viewed during the reporting period | Organic | `IMPRESSIONS_ALL_POSTS` | | Impressions | The number of times your posts published during the reporting period have been viewed | Organic | `IMPRESSIONS_BY_POST` | | Followers - Net New | The net new number of LinkedIn members who have followed your Page during the Reporting Period | | `NET_NEW_FOLLOWERS` | | Number of Posts | The number of posts you've published during the reporting period | Organic | `NUMBER_OF_POSTS` | | Page Views - All Posts | The number of times your Page was viewed during the reporting period | | `PAGE_VIEWS_ALL_POSTS` | | Reactions - All Posts | The number of reactions any of your posts received during the reporting period | Organic | `REACTIONS_ALL_POSTS` | | Reactions | The total number of reactions on your posts published during the reporting period | Organic | `REACTIONS_BY_POST` | | Shares - All Posts | The number of times any of your posts were shared during the reporting period | Organic | `SHARES_ALL_POSTS` | | Shares | The number of times your posts published during the reporting period were shared | Organic | `SHARES_BY_POST` | | Followers | The total number of followers you have on this channel | | `TOTAL_FOLLOWERS` | | 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` | | Unique Impressions | The number of times any of your posts were shown to unique LinkedIn members. Similar to Reach | Organic | `UNIQUE_IMPRESSIONS_ALL_POSTS` | | Unique Visitors - All Posts | The number of unique LinkedIn members who visited your Page during the reporting period | Organic | `UNIQUE_VISITORS_ALL_POSTS` | | Video Views | The number of times your videos published during the reporting period were viewed | Organic | `VIDEO_VIEWS_BY_POST` | | Watch Time | The total amount of time viewers spent watching your videos published during the Reporting Period | Organic | `WATCH_TIME_BY_POST` | ## Next steps You now have a JSON response with total performance metrics per brand and platform. Use this data to: * **Power BI dashboards** - Feed weekly or quarterly totals into Looker, Tableau, or other BI tools * **Compare performance** - Analyze growth between brands or channels * **Executive reporting** - Summarize KPIs for leadership **Related guides:** * [Visualize Time-Series Metrics with Graph Report →](/guides/graph-report) * [Analyze Post-Level Performance with Content Report →](/guides/content-report) * [Understand Owned vs Earned Reports →](/guides/owned-vs-earned) * [View the Full API Reference →](https://developers.dashsocial.com/reference/get_reports-data) # Monitor ad campaign metrics across brands Source: https://developer.dashsocial.com/guides/reporting/export-dashboard-report-data-via-api/social-advertising-report/monitor-ad-campaign-metrics-across-brands Retrieve aggregated ad campaign metrics across Meta Ads and TikTok Ads for multiple brands. Pull aggregated ad campaign metrics across Meta Ads and TikTok Ads. Use the data to monitor and compare ad campaign performance across brands. *** ## Use cases Tracking ad campaign performance manually across platforms wastes hours each week. Social advertising metric reports give you cross-platform ad performance benchmarks instantly. Compare ad spend and performance metrics across Meta and TikTok campaigns to optimize budget allocation Monitor ad campaign effectiveness across multiple brands from a single dashboard Analyze which campaigns drive the most clicks, conversions, and engagement across platforms *** ## Before you start Prerequisites: * **API Key** - Your authentication token - Get your API key from the [API Quickstart](https://developer.dashsocial.com/guides/get-started/quickstart). * **Brand ID** - Your brand's unique ID * **Connected Ad Accounts** - Meta Ads and/or TikTok Ads accounts connected in Dash Social Supported platforms: * Meta Ads * TikTok Ads **Connect ad accounts first:** Report on ad accounts connected in Dash Social only. Connect your ad accounts in **Dash Social → Settings → Ad Account Management** before using this API. ### Test in the dashboard first Preview ad campaign metrics in the Dash Social Dashboard to understand the data structure before pulling via API. *** ## Implementation ### Step 1: Get ad account IDs Get the ad account IDs for your connected advertising accounts. Each platform has a different endpoint. #### For Meta Ads Send a GET request: ```http theme={null} GET https://facebook.dashsocial.com/brands/{brand_id}/ad_accounts ``` Replace `{brand_id}` with your brand ID (e.g., `144`). #### For TikTok Ads Send a GET request: ```http theme={null} GET https://tiktok.dashsocial.com/marketing/brands/{brand_id}/ad_accounts ``` Replace `{brand_id}` with your brand ID (e.g., `144`). Sample response (both platforms): ```json theme={null} [ { "id": "1368643043296927", "name": "Demo Ad Account", "status": "ACTIVE" } ] ``` Collect each ad account `id` value. You'll use these in Step 2. ### Compare across platforms To compare multiple platforms, call both endpoints separately to get ad account IDs for Meta and TikTok. *** ### Step 2: Get ad campaigns Retrieve the ad campaigns under each ad account. Each platform has a different endpoint. #### For Meta Ads Send a PUT request: ```http theme={null} PUT https://facebook.dashsocial.com/brands/marketing_v2/campaigns body = { "ad_account_ids": ["1368643043296927"], "brand_ids": [144] } ``` #### For TikTok Ads Send a PUT request: ```http theme={null} PUT https://tiktok.dashsocial.com/marketing/ad_campaigns body = { "brand_ids": [144], "source_ad_account_ids": ["7113956961980284930"] } ``` Sample response (both platforms): ```json theme={null} [ { "brand_ids": [2000], "id": 9226231, "name": "Ad Campaign 1 GBP", "source_ad_account_id": "demo_ag10808192", "source_campaign_id": "demo1_3112", "source_created_time": "2024-01-09T10:00:00+00:00", "source_updated_time": null, "status": "PAUSED" } ] ``` Collect each `source_ad_account_id` and `source_campaign_id` value. Format as comma-separated values for the report API: * Ad account IDs: `1368643043296927,7113956961980284930` * Campaign IDs: `120236587787680490,120236587787680491` *** ### Step 3: Map your report parameters Map the available parameters before making the API call:
Parameter Description
`brand_ids` Your brand ID.
`channels` Ad platform to report on: * Meta Ads: `META_ADS` * TikTok Ads: `TIKTOK_ADS` Only one channel can be specified per request.
`metrics` Metric to report on. See [Metrics](#metrics) section below for all options. Request multiple metrics by separating with commas (e.g., `LINK_CLICKS,IMPRESSIONS,SPEND`)
`source_ad_account_ids` Comma-separated ad account IDs from Step 1: `1368643043296927,7113956961980284930`
`source_campaign_ids` Comma-separated campaign IDs from Step 2: `120236587787680490,120236587787680491`
`start_date` / `end_date` Reporting period in `YYYY-MM-DD` format
`context_start_date` / `context_end_date` Comparison date range for period-over-period analysis. Use same dates as `start_date` / `end_date` if no comparison needed
`report_type` Set to `ADS_TOTAL_METRIC` for this report
*** ### Step 4: Request the metric report Send a GET request using the parameters from Step 3. This example gets link clicks for Meta Ads campaigns: ```http theme={null} GET https://dashboard.dashsocial.com/reports/data?channels=META_ADS& start_date=2025-08-10& end_date=2025-08-20& metrics=LINK_CLICKS& brand_ids=144& report_type=ADS_TOTAL_METRIC& context_start_date=2024-07-01& context_end_date=2024-07-31& source_ad_account_ids=1368643043296927& source_campaign_ids=120236587787680490 ``` ### Compare multiple platforms Make separate requests for each channel: `META_ADS`, `TIKTOK_ADS`. Combine results in your dashboard or analytics tool. Sample response: ```json theme={null} { "data": { "120236587787680490": { "campaign_name": "Summer Sale Campaign", "data_type": "CAMPAIGN", "metrics": { "LINK_CLICKS": { "META_ADS": { "context": 1250, "context_change": 0.24, "value": 1550 } } }, "source_ad_account_id": "1368643043296927", "source_campaign_id": "120236587787680490", "user_has_access": true } }, "product_category": "ADS" } ``` *** ### Step 5: Interpret the response The response includes data for each ad campaign. #### Response structure Each campaign includes: * `data_type`: `CAMPAIGN` * `campaign_name`: Name of the ad campaign * `source_ad_account_id`: Ad account ID * `source_campaign_id`: Campaign ID * `metrics`: Object containing requested metrics * `value`: Metric total for the reporting period * `context`: Metric total for the comparison period * `context_change`: Decimal representing percent change (e.g., `0.24` = +24%, `-0.09` = -9%) **Common errors:** * **Invalid channel name** - Use `META_ADS` or `TIKTOK_ADS`. Only one channel per request. * **Invalid ad account or campaign ID** - Verify IDs match the responses from Steps 1-2. * **Missing context dates** - Include `context_start_date` and `context_end_date` for trend analysis. * **Null values in response** - Campaigns may return `null` if no data exists for the period. *** ## Metrics | Metric Name | Description | Metric API Name | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | | Clicks (All) - Ads | The total number of times the ads in your selected campaign were clicked during the Reporting Period | `CLICKS` | | CTR - Ads | The percentage of times people clicked your ads after seeing them during the Reporting Period. CTR = Total Clicks / Impressions | `CLICK_THROUGH_RATE` | | Conversion Rate - Ads | The percentage of people who saw the ad and performed the desired action | `CONVERSION_RATE` | | CPC - Ads | The average cost per click on your social ads during the Reporting Period.CPC = Spend / Total Clicks | `COST_PER_CLICK` | | CPM - Ads | The average cost per 1,000 impressions on your selected ad campaign during the Reporting Period. CPM = Total Spend / Impressions | `COST_PER_MILE` | | Engagements - Ads | The total number of engagements on all ads within your selected campaign during the Reporting Period | `ENGAGEMENTS` | | Engagement Rate - Ads | The total percentage of users who engaged with your selected campaign after seeing an ad during the Reporting Period. Engagement Rate = Total Engagements / Impressions | `ENGAGEMENT_RATE` | | Frequency - Ads | The average number of times users saw ads in your campaign during the Reporting Period | `FREQUENCY` | | Impressions - Ads | The total number of impressions the ads in your selected campaign received during the Reporting Period | `IMPRESSIONS` | | Link Clicks - Ads | The total number of times links on the ads in your selected campaign were clicked during the Reporting Period | `LINK_CLICKS` | | Page Engagements - Ads | The total number of engagements your page and its posts received from your ads during the Reporting Period | `PAGE_ENGAGEMENTS` | | Reach - Ads | The total number of unique accounts that saw ads within your selected campaign during the Reporting Period. | `REACH` | | ROAS - Ads | The total return on ad spend for your selected campaign, as provided by Meta.ROAS = Calculated Purchase Conversion Value / Amount Spent | `RETURN_ON_AD_SPEND` | | Amount Spent - Ads | The average cost per click on your social ads during the Reporting Period.CPC = Spend / Total Clicks | `TOTAL_SPENT` | | Video Views - Ads | The total number of times videos in your selected ad campaign were viewed for over 3 seconds during the Reporting Period | `VIDEO_VIEWS` | | Web Conversions - Ads | The estimated number of conversions your selected ad campaign received during the Reporting Period, as measured by the Meta Pixel installed on your website | `WEB_CONVERSIONS` | | Metric Name | Description | Metric API Name | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | | Clicks - Ads | The number of clicks on your ads that led to a destination, such as a website, during the Reporting Period. | `CLICKS` | | CTR - Ads | The percentage of times people saw your ad and performed a click (destination) during the reporting period. | `CLICK_THROUGH_RATE_DESTINATION` | | CPC - Ads | The average cost per click on your ads during the Reporting Period that led to a destination, such as a website or landing page. | `COST_PER_CLICK` | | CPM - Ads | The average cost per 1,000 impressions on your selected ad campaign during the Reporting Period. | `COST_PER_MILE` | | Engaged Views - Ads | The number of times that videos in your campaign have been played for at least 6 seconds, or received at least 1 engagement within 1 day of seeing the ad. | `ENGAGED_VIEW` | | Clicks (All) - Ads | The total number of all clicks on your ads, including link clicks, likes, shares, and comments, during the Reporting Period. | `ENGAGEMENTS` | | Frequency - Ads | The average number of times users saw ads in your campaign during the Reporting Period. | `FREQUENCY` | | Impressions - Ads | The total number of times users saw ads in your campaign during the Reporting Period. | `IMPRESSIONS` | | Reach - Ads | The estimated number of unique accounts that saw ads within your selected campaign during the Reporting Period. | `REACH` | | Real Time Conversions - Ads | The number of conversions your ad campaign received during the Reporting Period, based on the objective and settings selected in campaign setup. | `REAL_TIME_CONVERSIONS` | | Real Time Conversion Rate - Ads | The percentage of ad conversions achieved per impression on your ad campaign during the Reporting Period. | `REAL_TIME_CONVERSION_RATE` | | Amount Spent - Ads | The total amount of money you've spent on your selected ad campaign during the Reporting Period. | `TOTAL_SPENT` | | Video View 100% - Ads | The number of times that videos in your campaign were played to 100% completion during the Reporting Period. | `VIDEO_VIEWS_P100` | | Video View 50% - Ads | The number of times that videos in your campaign were played to 50% of their length during the Reporting Period. | `VIDEO_VIEWS_P50` | | Video Watched (6 sec) - Ads | The number of times that videos in your campaign were played for at least 6 seconds during the Reporting Period. Replays are not counted. | `VIDEO_WATCHED_6S` | ## Next steps With your ad campaign metrics, you can: * **Build performance dashboards** - Compare campaign performance across brands and platforms * **Track ROI trends** - Query monthly to spot campaign effectiveness changes * **Optimize ad spend** - Compare metrics across campaigns to identify top performers * **Inform budget allocation** - Use performance data to guide investment decisions across platforms Related guides: * [Track Ad Campaign Trends with Graph Reports](https://developer.dashsocial.com/guides/track-ad-campaign-trends-with-graph-reports) * [View Full API Reference](https://developers.dashsocial.com/reference/get_reports-data) # Social advertising report overview Source: https://developer.dashsocial.com/guides/reporting/export-dashboard-report-data-via-api/social-advertising-report/overview Monitor Meta and TikTok ad campaign performance using the social advertising report. Monitor and compare ad campaign performance across brands on Meta Ads and TikTok Ads to optimize budget allocation and track ROI. **Available report types:** Monitor Ad Campaign Metrics Across Brands Track Ad Campaign Trends with Graph Reports # Track ad campaign trends with graph reports Source: https://developer.dashsocial.com/guides/reporting/export-dashboard-report-data-via-api/social-advertising-report/track-ad-campaign-trends-with-graph-reports Visualize ad campaign performance trends over time using time-series data. Pull time-series ad campaign data to track performance trends over time. Use the data to visualize day-by-day metrics and identify patterns in ad campaign activity. *** ## Use cases Tracking ad campaign trends manually across weeks or months wastes hours. Graph reports give you time-series data ready to visualize instantly. Visualize daily campaign performance to spot trends and optimize in real-time Compare ad performance across date ranges to understand when campaigns perform best Track cost-per-click and conversion trends over time to optimize budget allocation *** ## Before you start Prerequisites: * **API Key** - Your authentication token - Get your API key from the [API Quickstart](https://developer.dashsocial.com/guides/get-started/quickstart). * **Brand ID** - Your brand's unique ID * **Connected Ad Accounts** - Meta Ads and/or TikTok Ads accounts connected in Dash Social Supported platforms: * Meta Ads * TikTok Ads **Connect ad accounts first:** Report on ad accounts connected in Dash Social only. Connect your ad accounts in **Dash Social → Settings → Ad Account Management** before using this API. ### Test in the dashboard first Preview ad campaign graph reports in the Dash Social Dashboard to understand the data structure before pulling via API. *** ## Implementation ### Step 1: Get ad account IDs Get the ad account IDs for your connected advertising accounts. Each platform has a different endpoint. #### For Meta Ads Send a GET request: ```http theme={null} GET https://facebook.dashsocial.com/brands/{brand_id}/ad_accounts ``` Replace `{brand_id}` with your brand ID (e.g., `144`). #### For TikTok Ads Send a GET request: ```http theme={null} GET https://tiktok.dashsocial.com/marketing/brands/{brand_id}/ad_accounts ``` Replace `{brand_id}` with your brand ID (e.g., `144`). Sample response (both platforms): ```json theme={null} [ { "id": "1368643043296927", "name": "Demo Ad Account", "status": "ACTIVE" } ] ``` Collect each ad account `id` value. You'll use these in Step 2. ### Compare across platforms To compare multiple platforms, call both endpoints separately to get ad account IDs for Meta and TikTok. *** ### Step 2: Get ad campaigns Retrieve the ad campaigns under each ad account. Each platform has a different endpoint. #### For Meta Ads Send a PUT request: ```http theme={null} PUT https://facebook.dashsocial.com/brands/marketing_v2/campaigns body = { "ad_account_ids": ["1368643043296927"], "brand_ids": [144] } ``` #### For TikTok Ads Send a PUT request: ```http theme={null} PUT https://tiktok.dashsocial.com/marketing/ad_campaigns body = { "brand_ids": [144], "source_ad_account_ids": ["7113956961980284930"] } ``` Sample response (both platforms): ```json theme={null} [ { "brand_ids": [2000], "id": 9226231, "name": "Ad Campaign 1 GBP", "source_ad_account_id": "demo_ag10808192", "source_campaign_id": "demo1_3112", "source_created_time": "2024-01-09T10:00:00+00:00", "source_updated_time": null, "status": "PAUSED" } ] ``` Collect each `source_ad_account_id` and `source_campaign_id` value. Format as comma-separated values for the report API: * Ad account IDs: `1368643043296927,7113956961980284930` * Campaign IDs: `120236587787680490,120236587787680491` *** ### Step 3: Map your report parameters Map the available parameters before making the API call:
Parameter Description
`brand_ids` Your brand ID.
`channels` Ad platform to report on: * Meta Ads: `META_ADS` * TikTok Ads: `TIKTOK_ADS` Only one channel can be specified per request.
`metrics` Metric to track over time. See [Metrics](#metrics) section below for all options. Request multiple metrics by separating with commas (e.g., `LINK_CLICKS,IMPRESSIONS,SPEND`)
`source_ad_account_ids` Comma-separated ad account IDs from Step 1: `1368643043296927,7113956961980284930`
`source_campaign_ids` Comma-separated campaign IDs from Step 2: `120236587787680490,120236587787680491`
`start_date` / `end_date` Reporting period in `YYYY-MM-DD` format. The graph report returns daily data points for each date in this range.
`context_start_date` / `context_end_date` Comparison date range for period-over-period analysis. Use same dates as `start_date` / `end_date` if no comparison needed
`report_type` Set to `ADS_GRAPH` for time-series data
`time_scale` Time granularity for data aggregation: * `DAILY` - Daily data points (default) * `MONTHLY` - Monthly data points Optional. Defaults to `DAILY` if not specified.
*** ### Step 4: Request the graph report Send a GET request using the parameters from Step 3. This example gets daily link clicks for Meta Ads campaigns during August 2025: ```http theme={null} GET https://dashboard.dashsocial.com/reports/data?channels=META_ADS& start_date=2025-08-10& end_date=2025-08-20& metrics=LINK_CLICKS& brand_ids=144& report_type=ADS_GRAPH& context_start_date=2024-07-01& context_end_date=2024-07-31& source_ad_account_ids=1368643043296927& source_campaign_ids=120236587787680490 ``` ### Compare multiple platforms Make separate requests for each channel: `META_ADS`, `TIKTOK_ADS`. Combine results in your dashboard or analytics tool. Sample response: ```json theme={null} { "data": { "120236587787680490": { "META_ADS": { "LINK_CLICKS": { "2025-08-10": 120.0, "2025-08-11": 145.0, "2025-08-12": 132.0, "2025-08-13": 158.0, "2025-08-14": 167.0, "2025-08-15": 189.0, "2025-08-16": 201.0, "2025-08-17": 178.0, "2025-08-18": 194.0, "2025-08-19": 156.0, "2025-08-20": 143.0 } }, "campaign_name": "Summer Sale Campaign", "data_type": "CAMPAIGN", "metrics": { "LINK_CLICKS": { "META_ADS": { "2025-08-10": 120.0, "2025-08-11": 145.0, "2025-08-12": 132.0, "2025-08-13": 158.0, "2025-08-14": 167.0, "2025-08-15": 189.0, "2025-08-16": 201.0, "2025-08-17": 178.0, "2025-08-18": 194.0, "2025-08-19": 156.0, "2025-08-20": 143.0 } } }, "source_ad_account_id": "1368643043296927", "source_campaign_id": "120236587787680490", "user_has_access": true } }, "product_category": "ADS" } ``` *** ### Step 5: Interpret the response The response includes time-series data for each ad campaign. #### Response structure Each campaign includes: * **`data_type`**: `CAMPAIGN` * **`campaign_name`**: Name of the ad campaign * **`source_ad_account_id`**: Ad account ID * **`source_campaign_id`**: Campaign ID * **Date-keyed metrics**: Each metric is organized by date (e.g., `"2025-08-10": 120.0`). This makes it easy to plot on line charts or trend graphs. #### Example insights From the sample response: * **Summer Sale Campaign** had peak performance on August 16 with 201 link clicks * Performance showed an upward trend from August 10-16 * Click volume decreased in the final days of the period (August 17-20) **Common errors:** * **Invalid channel name** - Use `META_ADS` or `TIKTOK_ADS`. Only one channel per request. * **Invalid ad account or campaign ID** - Verify IDs match the responses from Steps 1-2. * **Missing context dates** - Include `context_start_date` and `context_end_date` for trend analysis. * **Sparse data** - Some dates may have null values if the campaign was paused or had no activity. *** ## Metrics | Metric Name | Description | Metric API Name | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | | Clicks (All) - Ads | The total number of times the ads in your selected campaign were clicked during the Reporting Period | `CLICKS` | | CTR - Ads | The percentage of times people clicked your ads after seeing them during the Reporting Period. CTR = Total Clicks / Impressions | `CLICK_THROUGH_RATE` | | Conversion Rate - Ads | The percentage of people who saw the ad and performed the desired action | `CONVERSION_RATE` | | CPC - Ads | The average cost per click on your social ads during the Reporting Period.CPC = Spend / Total Clicks | `COST_PER_CLICK` | | CPM - Ads | The average cost per 1,000 impressions on your selected ad campaign during the Reporting Period. CPM = Total Spend / Impressions | `COST_PER_MILE` | | Engagements - Ads | The total number of engagements on all ads within your selected campaign during the Reporting Period | `ENGAGEMENTS` | | Engagement Rate - Ads | The total percentage of users who engaged with your selected campaign after seeing an ad during the Reporting Period. Engagement Rate = Total Engagements / Impressions | `ENGAGEMENT_RATE` | | Frequency - Ads | The average number of times users saw ads in your campaign during the Reporting Period | `FREQUENCY` | | Impressions - Ads | The total number of impressions the ads in your selected campaign received during the Reporting Period | `IMPRESSIONS` | | Link Clicks - Ads | The total number of times links on the ads in your selected campaign were clicked during the Reporting Period | `LINK_CLICKS` | | Page Engagements - Ads | The total number of engagements your page and its posts received from your ads during the Reporting Period | `PAGE_ENGAGEMENTS` | | Reach - Ads | The total number of unique accounts that saw ads within your selected campaign during the Reporting Period. | `REACH` | | ROAS - Ads | The total return on ad spend for your selected campaign, as provided by Meta.ROAS = Calculated Purchase Conversion Value / Amount Spent | `RETURN_ON_AD_SPEND` | | Amount Spent - Ads | The average cost per click on your social ads during the Reporting Period.CPC = Spend / Total Clicks | `TOTAL_SPENT` | | Video Views - Ads | The total number of times videos in your selected ad campaign were viewed for over 3 seconds during the Reporting Period | `VIDEO_VIEWS` | | Web Conversions - Ads | The estimated number of conversions your selected ad campaign received during the Reporting Period, as measured by the Meta Pixel installed on your website | `WEB_CONVERSIONS` | | Metric Name | Description | Metric API Name | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | | Clicks - Ads | The number of clicks on your ads that led to a destination, such as a website, during the Reporting Period. | `CLICKS` | | CTR - Ads | The percentage of times people saw your ad and performed a click (destination) during the reporting period. | `CLICK_THROUGH_RATE_DESTINATION` | | CPC - Ads | The average cost per click on your ads during the Reporting Period that led to a destination, such as a website or landing page. | `COST_PER_CLICK` | | CPM - Ads | The average cost per 1,000 impressions on your selected ad campaign during the Reporting Period. | `COST_PER_MILE` | | Engaged Views - Ads | The number of times that videos in your campaign have been played for at least 6 seconds, or received at least 1 engagement within 1 day of seeing the ad. | `ENGAGED_VIEW` | | Clicks (All) - Ads | The total number of all clicks on your ads, including link clicks, likes, shares, and comments, during the Reporting Period. | `ENGAGEMENTS` | | Frequency - Ads | The average number of times users saw ads in your campaign during the Reporting Period. | `FREQUENCY` | | Impressions - Ads | The total number of times users saw ads in your campaign during the Reporting Period. | `IMPRESSIONS` | | Reach - Ads | The estimated number of unique accounts that saw ads within your selected campaign during the Reporting Period. | `REACH` | | Real Time Conversions - Ads | The number of conversions your ad campaign received during the Reporting Period, based on the objective and settings selected in campaign setup. | `REAL_TIME_CONVERSIONS` | | Real Time Conversion Rate - Ads | The percentage of ad conversions achieved per impression on your ad campaign during the Reporting Period. | `REAL_TIME_CONVERSION_RATE` | | Amount Spent - Ads | The total amount of money you've spent on your selected ad campaign during the Reporting Period. | `TOTAL_SPENT` | | Video View 100% - Ads | The number of times that videos in your campaign were played to 100% completion during the Reporting Period. | `VIDEO_VIEWS_P100` | | Video View 50% - Ads | The number of times that videos in your campaign were played to 50% of their length during the Reporting Period. | `VIDEO_VIEWS_P50` | | Video Watched (6 sec) - Ads | The number of times that videos in your campaign were played for at least 6 seconds during the Reporting Period. Replays are not counted. | `VIDEO_WATCHED_6S` | ## Next steps With your ad campaign graph data, you can: * **Build trend visualizations** - Plot each campaign as a separate line on a chart * **Identify performance patterns** - Spot weekly patterns or optimal days for ad delivery * **Track campaign lifecycles** - Visualize performance from launch through optimization * **Compare campaign effectiveness** - Benchmark multiple campaigns against each other Related guides: * [Monitor Ad Campaign Metrics Across Brands](https://developer.dashsocial.com/guides/monitor-ad-campaign-metrics-across-brands) * [View Full API Reference](https://developers.dashsocial.com/reference/get_reports-data) # Get aggregated social listening metrics Source: https://developer.dashsocial.com/guides/reporting/export-dashboard-report-data-via-api/social-listening-report/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} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} curl 'https://auth.dashsocial.com/api/self' \ -H 'Authorization: Bearer {token}' ``` Sample response: ```json theme={null} theme={null} theme={null} theme={null} theme={null} 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. 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). # Social listening report overview Source: https://developer.dashsocial.com/guides/reporting/export-dashboard-report-data-via-api/social-listening-report/overview Monitor brand sentiment trends using the social listening dashboard report. Measure Topic performance across social channels. Pull aggregated metrics or time-series trends for keyword-based topics to track brand sentiment and mention volume. 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). **Available report types:** Get Aggregated Social Listening Metrics Track Social Listening Trends with Graph Report # Track social listening trends with graph report Source: https://developer.dashsocial.com/guides/reporting/export-dashboard-report-data-via-api/social-listening-report/track-social-listening-trends-with-graph-report Track social listening metrics over time with daily or monthly granularity. Use graph reports to track how social listening metrics change over time. Pull daily or monthly time-series data to visualize conversation trends, measure campaign momentum, and analyze brand mention patterns in BI tools like Power BI, Tableau, or Looker. 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 Tracking conversation volume and engagement over time reveals campaign impact and identifies momentum shifts. Graph reports provide day-by-day or month-by-month breakdowns for trend analysis. Chart daily engagement and post volume during product launches to measure conversation growth Track engagement trends to identify when brand conversations gain or lose momentum Compare monthly metrics against previous periods to benchmark performance Visualize social listening KPIs in Tableau or Power BI for stakeholder dashboards ## Before you start Make sure you have: * **API Key**: Your authentication token * **Brand ID**: The brand to track social listening data for See our [API Quickstart](https://developer.dashsocial.com/guides/get-started/quickstart) for help getting these. **Need to create a topic?** See [Monitor Brand Mentions with Social Listening API](/guides/monitor-brand-mentions-with-social-listening-api) to set up your first topic. *** ## Implementation ### Step 1: Get your topic ID Retrieve your topic ID to identify which conversation 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} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} curl 'https://auth.dashsocial.com/api/self' \ -H 'Authorization: Bearer {token}' ``` Sample response: ```json theme={null} theme={null} theme={null} theme={null} theme={null} 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. 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))" } } } ] } ``` Save the `id` value. This is your `topic_id` for all subsequent requests. **Already have a topic ID?** Skip to Step 2. ### 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 daily 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 }, "TOPIC_11423": { "data_type": "TOPIC", "metrics": { "AVERAGE_ENGAGEMENTS_PER_POST": { "ALL_CHANNELS": { "2025-05-01 00:00:00": 614, "2025-05-02 00:00:00": 466, "2025-05-03 00:00:00": 467, "2025-05-04 00:00:00": 670, "2025-05-05 00:00:00": 329, "2025-05-06 00:00:00": 664, "2025-05-07 00:00:00": 823 } } } }, "metrics": { "AVERAGE_ENGAGEMENTS_PER_POST": { "ALL_CHANNELS": { "2025-05-01 00:00:00": 614, "2025-05-02 00:00:00": 466, "2025-05-03 00:00:00": 467, "2025-05-04 00:00:00": 670, "2025-05-05 00:00:00": 329, "2025-05-06 00:00:00": 664, "2025-05-07 00:00:00": 823 } } } }, "product_category": "LISTENING" } ``` **Understanding the response:** Topic data is nested under `TOPIC_{id}`. Brand metadata appears at the top level under the brand ID. Metric values are organized by date with daily breakdowns (e.g., May 1 had 614 average engagements, May 7 had 823). **Date format matters:** Always use `YYYY-MM-DD` format for dates (e.g., `2025-05-01`). Other formats will cause errors. *** ## 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 time-series data to: * **Visualize trends**: Import data into Power BI, Tableau, or Looker to create executive dashboards * **Identify momentum shifts**: Compare daily or monthly metrics to spot when conversations accelerate or decline * **Measure campaign impact**: Track metrics before, during, and after campaigns to quantify effectiveness * **Compare time periods**: Use context dates to benchmark current performance against historical data **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 graph reports for time-series data. Social listening also supports: * [Metric reports](/guides/get-aggregated-social-listening-metrics) for aggregated totals * [Social Listening API](/guides/monitor-brand-mentions-with-social-listening-api) for detailed post-level data # Calculate total social impact across channels Source: https://developer.dashsocial.com/guides/reporting/export-dashboard-report-data-via-api/tsi-report/calculate-total-social-impact-across-channels Measure unified social presence using Total Social Impact metrics across owned and earned channels. Measure your brand's total social impact combining owned and earned content. This guide shows you how to pull Total Social Impact (TSI) metrics using the metric report. TSI unifies your brand's social presence by aggregating both content you publish and content where others mention your brand. *** ## Use cases Calculating combined social impact manually across owned and earned content is complex. TSI metric reports give you unified totals in seconds. Build quarterly reports showing total social impact across all channels for leadership presentations Measure combined impact from paid posts and organic influencer mentions to calculate true campaign ROI Compare total social impact across Instagram, TikTok, and Facebook to identify your most valuable channels Track how your unified social presence grows over time by comparing TSI scores across quarters *** ## Before you start Make sure you have: * **API Key** - Your authentication token from Dash Social developer settings * **Brand ID** - The ID for each brand you want to report on Check out our [API Quickstart](https://developer.dashsocial.com/guides/get-started/quickstart) if you need help getting these. **Test in the UI first:** Create a Dashboard in the Dash Social UI and configure your TSI report there. This previews the metrics and validates your filters before writing code. **What TSI measures:** Total Social Impact combines impressions from your published content (owned) with impressions from posts where others mention your brand (earned). This gives you a complete view of your social presence beyond just content you create. *** **Supported platforms** This report supports these channels: * Instagram * Instagram Stories * Instagram UGC * TikTok * TikTok UGC * Facebook * Pinterest * YouTube * LinkedIn * X **Understanding channel types:** Channels with "UGC" track earned content (mentions). Channels without "UGC" track owned content (your posts). Request both to get complete social impact across owned and earned. **About TSI metric reports** TSI reports support only one metric: Total Social Impact (`TOTAL_TSI`). This combines impressions from owned and earned content using Dash's proprietary scoring algorithm. *** ## 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,146`)
`channels` Social platforms to include: * Instagram: `INSTAGRAM` * Instagram Stories: `INSTAGRAM_STORIES` * Instagram UGC: `INSTAGRAM_UGC` * TikTok: `TIKTOK` * TikTok UGC: `TIKTOK_UGC` * Facebook: `FACEBOOK` * Pinterest: `PINTEREST` * YouTube: `YOUTUBE` * LinkedIn: `LINKEDIN` * X: `TWITTER` Include both owned and UGC channels for complete TSI (e.g., `INSTAGRAM,INSTAGRAM_UGC,TIKTOK,TIKTOK_UGC`)
`metrics` Set to `TOTAL_TSI` - measures your unified social presence by combining impressions from owned content (posts you publish) and earned content (brand mentions by others)
`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
*** ### Step 2: Make the API call Send a GET request using the parameters from Step 1. This example gets Total Social Impact for brand `144` across all channels from May 1-7, with April 1-7 as the comparison period. ```http theme={null} GET https://dashboard.dashsocial.com/reports/data ?channels=INSTAGRAM,INSTAGRAM_STORIES,INSTAGRAM_UGC,TIKTOK,TIKTOK_UGC,FACEBOOK,PINTEREST,YOUTUBE,LINKEDIN,TWITTER &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=TOTAL_TSI &report_type=TOTAL_METRIC ``` **Date format matters:** Always use `YYYY-MM-DD` format for dates (e.g., `2025-05-01`). Other formats will cause errors. **Include all channels:** For the most accurate TSI score, include all owned and UGC channels in your request. TSI calculations work best when measuring complete social presence. #### Sample response The response returns TSI totals for each channel, organized by brand. The `value` field shows TSI for your reporting period. The `context` field shows the comparison period total. The `context_change` field shows the percentage change. ```json theme={null} { "data": { "144": { "avatar": "https://cdn.dashsocial.com/avatars/2306810931.jpeg", "data_type": "BRAND", "metrics": { "TOTAL_TSI": { "FACEBOOK": { "context": 24146, "context_change": 0.026339766420939287, "value": 24782 }, "INSTAGRAM": { "context": 787708, "context_change": 0.0014332722277798373, "value": 788837 }, "INSTAGRAM_STORIES": { "context": 1664, "context_change": 0.009615384615384616, "value": 1680 }, "INSTAGRAM_UGC": { "context": 3037, "context_change": 0.0009878169245966415, "value": 3040 }, "LINKEDIN": { "context": 1719, "context_change": 0.38801628853984876, "value": 2386 }, "PINTEREST": { "context": 3272508, "context_change": 0.010491647384819227, "value": 3306842 }, "TIKTOK": { "context": 109518, "context_change": 0.01897404992786574, "value": 111596 }, "TIKTOK_UGC": { "context": 13286, "context_change": 0.08821315670630739, "value": 14458 }, "TWITTER": { "context": 47300, "context_change": 0.0038054968287526427, "value": 47480 }, "YOUTUBE": { "context": 230, "context_change": 0.0, "value": 230 } } }, "name": "sunny.today", "user_has_access": true } }, "product_category": "TSI" } ``` **Understanding the response:** TSI scores are organized by brand ID and broken down by channel. In this example, brand `144` ("sunny.today") achieved a total Instagram TSI of 788,837 during May 1-7, up 0.14% from 787,708 during April 1-7. The largest growth came from LinkedIn (38.8% increase) and TikTok UGC (8.8% increase). Feed this data into your BI tool or executive dashboard to track unified social impact across owned and earned content. **Calculating total impact:** To get overall TSI across all channels, sum the `value` fields for each channel. In this example, brand 144's total TSI is 4,304,331 (sum of all channels). *** ## Next steps * [Visualize TSI Trends Over Time with Graph Report →](/guides/tsi-graph-report) * [Compare Owned vs Earned Performance →](/guides/owned-vs-earned) * [Track Individual Post Performance with Content Report →](/guides/content-report) * [View the Full API Reference →](https://developers.dashsocial.com/reference/get_reports-data) # TSI report overview Source: https://developer.dashsocial.com/guides/reporting/export-dashboard-report-data-via-api/tsi-report/overview Measure Total Social Impact by combining owned and earned metrics into a unified view. Combines owned and earned metrics using Dash's proprietary scoring to measure unified social presence and total brand impact. **Available report types:** Calculate Total Social Impact Across Channels Track TSI Trends Over Time with Graph Report # Track TSI trends over time with graph report Source: https://developer.dashsocial.com/guides/reporting/export-dashboard-report-data-via-api/tsi-report/track-tsi-trends-over-time-with-graph-report Visualize how Total Social Impact changes daily to identify performance patterns over time. Track how your Total Social Impact changes day by day across all channels. This guide shows you how to pull TSI time-series data using the Graph report. You'll get daily breakdowns ready to visualize trends and measure unified social presence over time. *** ## Use cases Measuring TSI at a single point in time doesn't show you how your combined owned and earned presence evolves. Graph reports give you daily TSI values so you can spot growth patterns, track campaign momentum, and demonstrate social impact improvements to stakeholders. Chart daily TSI during campaign periods to measure how owned posts and earned mentions together drive social presence growth Visualize TSI trends across Q1, Q2, Q3, and Q4 in executive dashboards to show year-over-year social impact improvements Track which channels (Instagram, TikTok, etc.) are growing TSI fastest to identify where to invest more resources Compare daily TSI from owned content versus UGC mentions to understand which drives more total impact *** ## Before you start Make sure you have: * **API access token** with permissions to the relevant brand. * **Brand ID** for the account you want to query. See [API Quickstart](/guides/get-started/quickstart) for more details. **Test in the UI first:** Create a Dashboard in the Dash Social UI and configure your TSI graph report there. This lets you preview the time-series behavior and validate that your filters return the right data before writing any code. **What TSI measures:** Total Social Impact combines impressions from your published content (owned) with impressions from posts where others mention your brand (earned). This gives you a complete view of your social presence beyond just content you create. *** **Supported platforms** This report supports these channels: * Instagram * Instagram Stories * Instagram UGC * TikTok * TikTok UGC * Facebook * Pinterest * YouTube * LinkedIn * X **Understanding channel types:** Channels with "UGC" track earned content (mentions). Channels without "UGC" track owned content (your posts). Request both to get complete social impact across owned and earned. **About TSI graph reports** Graph reports return daily TSI values organized by date. Use graph reports when you want to chart trends or visualize changes over time. TSI reports support only one metric: Total Social Impact (`TOTAL_TSI`). This combines impressions from owned and earned content using Dash's proprietary scoring algorithm. *** ## 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,146`)
`channels` Social platforms to include: * Instagram: `INSTAGRAM` * Instagram Stories: `INSTAGRAM_STORIES` * Instagram UGC: `INSTAGRAM_UGC` * TikTok: `TIKTOK` * TikTok UGC: `TIKTOK_UGC` * Facebook: `FACEBOOK` * Pinterest: `PINTEREST` * YouTube: `YOUTUBE` * LinkedIn: `LINKEDIN` * X: `TWITTER` Include both owned and UGC channels for complete TSI (e.g., `INSTAGRAM,INSTAGRAM_UGC,TIKTOK,TIKTOK_UGC`)
`metrics` Set to `TOTAL_TSI` - measures your unified social presence by combining impressions from owned content (posts you publish) and earned content (brand mentions by others)
`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 `GRAPH` for time-series data
*** ### Step 2: Make the API call Send a GET request using the parameters from Step 1. This example gets daily Total Social Impact for brand `144` across all channels from May 1-7, with April 1-7 as the comparison period. ```http theme={null} GET https://dashboard.dashsocial.com/reports/data ?channels=INSTAGRAM,INSTAGRAM_STORIES,INSTAGRAM_UGC,TIKTOK,TIKTOK_UGC,FACEBOOK,PINTEREST,YOUTUBE,LINKEDIN,TWITTER &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=TOTAL_TSI &report_type=GRAPH ``` **Date format matters:** Always use `YYYY-MM-DD` format for dates (e.g., `2025-05-01`). Other formats will cause errors. **Include all channels:** For the most accurate TSI score, include all owned and UGC channels in your request. TSI calculations work best when measuring complete social presence. #### Sample response The response returns time-series TSI data organized by date. Each channel has daily values for your reporting period. ```json theme={null} { "data": { "144": { "avatar": "https://cdn.dashsocial.com/avatars/2306810931.jpeg", "data_type": "BRAND", "metrics": { "TOTAL_TSI": { "FACEBOOK": { "2025-05-01T00:00:00.000Z": 3498, "2025-05-02T00:00:00.000Z": 3612, "2025-05-03T00:00:00.000Z": 3544, "2025-05-04T00:00:00.000Z": 3729, "2025-05-05T00:00:00.000Z": 3655, "2025-05-06T00:00:00.000Z": 3421, "2025-05-07T00:00:00.000Z": 3323 }, "INSTAGRAM": { "2025-05-01T00:00:00.000Z": 112683, "2025-05-02T00:00:00.000Z": 115421, "2025-05-03T00:00:00.000Z": 118337, "2025-05-04T00:00:00.000Z": 121086, "2025-05-05T00:00:00.000Z": 119542, "2025-05-06T00:00:00.000Z": 116198, "2025-05-07T00:00:00.000Z": 85570 }, "INSTAGRAM_STORIES": { "2025-05-01T00:00:00.000Z": 240, "2025-05-02T00:00:00.000Z": 235, "2025-05-03T00:00:00.000Z": 243, "2025-05-04T00:00:00.000Z": 238, "2025-05-05T00:00:00.000Z": 241, "2025-05-06T00:00:00.000Z": 248, "2025-05-07T00:00:00.000Z": 235 }, "INSTAGRAM_UGC": { "2025-05-01T00:00:00.000Z": 434, "2025-05-02T00:00:00.000Z": 441, "2025-05-03T00:00:00.000Z": 438, "2025-05-04T00:00:00.000Z": 445, "2025-05-05T00:00:00.000Z": 447, "2025-05-06T00:00:00.000Z": 442, "2025-05-07T00:00:00.000Z": 393 }, "PINTEREST": { "2025-05-01T00:00:00.000Z": 471835, "2025-05-02T00:00:00.000Z": 473691, "2025-05-03T00:00:00.000Z": 472548, "2025-05-04T00:00:00.000Z": 475102, "2025-05-05T00:00:00.000Z": 474236, "2025-05-06T00:00:00.000Z": 471891, "2025-05-07T00:00:00.000Z": 467539 }, "TIKTOK": { "2025-05-01T00:00:00.000Z": 15942, "2025-05-02T00:00:00.000Z": 16128, "2025-05-03T00:00:00.000Z": 16335, "2025-05-04T00:00:00.000Z": 16542, "2025-05-05T00:00:00.000Z": 16221, "2025-05-06T00:00:00.000Z": 15883, "2025-05-07T00:00:00.000Z": 14545 }, "TIKTOK_UGC": { "2025-05-01T00:00:00.000Z": 2065, "2025-05-02T00:00:00.000Z": 2083, "2025-05-03T00:00:00.000Z": 2091, "2025-05-04T00:00:00.000Z": 2104, "2025-05-05T00:00:00.000Z": 2098, "2025-05-06T00:00:00.000Z": 2077, "2025-05-07T00:00:00.000Z": 1940 }, "TWITTER": { "2025-05-01T00:00:00.000Z": 6783, "2025-05-02T00:00:00.000Z": 6791, "2025-05-03T00:00:00.000Z": 6805, "2025-05-04T00:00:00.000Z": 6812, "2025-05-05T00:00:00.000Z": 6798, "2025-05-06T00:00:00.000Z": 6755, "2025-05-07T00:00:00.000Z": 6536 }, "YOUTUBE": { "2025-05-01T00:00:00.000Z": 33, "2025-05-02T00:00:00.000Z": 33, "2025-05-03T00:00:00.000Z": 33, "2025-05-04T00:00:00.000Z": 33, "2025-05-05T00:00:00.000Z": 33, "2025-05-06T00:00:00.000Z": 33, "2025-05-07T00:00:00.000Z": 33 } } }, "name": "sunny.today", "user_has_access": true } }, "product_category": "TSI" } ``` **Understanding the response:** TSI values are organized by brand ID and broken down by channel and date. In this example: * Brand `144` ("sunny.today") achieved Instagram TSI of 112,683 on May 1, growing to 121,086 by May 4 before declining to 85,570 on May 7 * The dates are in ISO 8601 format with timezone (`2025-05-01T00:00:00.000Z`) * Pinterest consistently drove the highest daily TSI values (around 471k-475k per day) * Instagram showed strong growth mid-week but dropped on the weekend Use this time-series data in BI tools like Power BI, Tableau, or Looker to create trend charts and spot patterns in your unified social impact. **Calculating total daily TSI:** To get overall TSI for a specific date across all channels, sum the values for that date. For example, on May 1, brand 144's total TSI was 613,854 (sum of all channels on that date). **Want aggregated totals instead?** Use the [TSI Metric report](/guides/calculate-total-social-impact-across-channels) to get summed KPIs without time breakdowns. *** ## Next steps * [Calculate Total Social Impact Across Channels →](/guides/calculate-total-social-impact-across-channels) * [Compare Owned vs Earned Performance →](/guides/owned-vs-earned) * [Track Individual Post Performance with Content Report →](/guides/content-report) * [View the Full API Reference →](https://developers.dashsocial.com/reference/get_reports-data) # Get post performance data across all channels Source: https://developer.dashsocial.com/guides/reporting/get-post-performance-data-across-all-channels Use the media/v2 endpoint to access post stats across all your connected social channels. This guide shows you how to use the `media/v2` endpoint to get access to your post stats for all your channels. ## Use case examples Each of these use cases highlights how teams use the `media/v2` endpoint: Pull all posts published during a campaign window to analyze impact over time. Filter by source type to analyze performance of user-generated content separately. Fetch media from a single social platform to create focused reports or dashboards. Compare performance across media types and surface high-performing assets. ## Before you start Make sure you have: * **API access token** with permissions to the relevant brand. * **Brand ID** for the account you want to query. See [API Quickstart](/guides/get-started/quickstart) for more details. ## Setup and considerations Endpoint: `PUT https://library-backend.dashsocial.com/brands/{brand_id}/media/v2` ### Rate limit To help you avoid hitting rate limits and ensure smooth data retrieval, follow these best practices: * Set `limit=99` in your requests to keep requests efficient and light, allowing you to retrieve more data per minute. * Add a 1000ms (1 second) delay between requests to prevent hitting limits when paginating. ### Data freshness Metric updates vary by post age: * Recently published posts: updated more frequently * Older posts: updated less frequently For most accurate reporting, focus on data from the last 90 days. ## Implementation To implement requests to the `media/v2` endpoint, refer to the [endpoint's reference](https://developer.dashsocial.com/api-reference/library/media/retrieve-media) for detailed information. Here is an example request with the appropriate filters: ```http theme={null} PUT https://library-backend.dashsocial.com/brands/{brand_id}/media/v2 body = { "limit":99, "offset":0, "filters":{ "brand_media_types":[ "INSTAGRAM_OWNED" ], "source_created_at":{ "end":"2022-01-10", "start":"2022-01-01" } } } ``` ### Key query parameters **`brand_media_types`** — which platform and content type to include. Expand a platform below to see all valid values: | Value | Description | | ---------------------- | ------------------- | | `INSTAGRAM_OWNED` | Brand-owned content | | `INSTAGRAM_UGC` | UGC | | `INSTAGRAM_OTHER` | Competitor content | | `INSTAGRAM_OWNED_IGTV` | Brand-owned IGTV | | `INSTAGRAM_UGC_IGTV` | UGC IGTV | | `INSTAGRAM_OTHER_IGTV` | Competitor IGTV | | `INSTAGRAM_STORY` | Brand-owned stories | | `INSTAGRAM_STORY_UGC` | UGC stories | | Value | Description | | ----------------- | ------------------- | | `PINTEREST_OWNED` | Brand-owned content | | Value | Description | | -------------------- | ------------------------- | | `FACEBOOK_OWNED` | Brand-owned content | | `FACEBOOK_LINK` | Posts with external links | | `FACEBOOK_TEXT_LINK` | Text with links | | `FACEBOOK_TEXT` | Text-only posts | | Value | Description | | -------------------- | ------------------- | | `TWITTER_OWNED` | Brand-owned content | | `TWITTER_OWNED_LINK` | Posts with links | | `TWITTER_OWNED_TEXT` | Text-only posts | | Value | Description | | -------------- | ------------------- | | `TIKTOK_OWNED` | Brand-owned content | | Value | Description | | --------------- | ------------------- | | `YOUTUBE_OWNED` | Brand-owned content | | Value | Description | | ---------- | ----------- | | `UPLOADED` | Uploads | Due to a technical limitation, you cannot query Instagram (`INSTAGRAM_OWNED`, `INSTAGRAM_STORY`) media types in the same request as other social media platforms. Always separate Instagram queries from other social media platforms. **`source_created_at`** — date range to filter posts. **`limit`** — max results per page. Set `limit=99` for efficiency. **`offset`** — pagination offset. ### Full example A complete implementation that handles pagination and rate limiting: ```javascript Node.js theme={null} const fetch = require('node-fetch'); // Only needed if using Node.js < 18 async function fetchPostMetrics({ brandId, token, platform, startDate, endDate }) { const baseUrl = `https://library-backend.dashsocial.com/brands/${brandId}/media/v2`; const body = { limit: 99, offset: 0, filters: { brand_media_types: [platform], // e.g., 'INSTAGRAM_OWNED' source_created_at: { start: startDate, end: endDate } } }; const headers = { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` }; async function delay(ms) { return new Promise(resolve => setTimeout(resolve, ms)); } let allData = []; let nextUrl = `${baseUrl}?limit=99`; while (nextUrl) { const response = await fetch(nextUrl, { method: 'PUT', headers, body: JSON.stringify(body) }); if (!response.ok) { console.error(`Request failed: ${response.status} ${response.statusText}`); break; } const result = await response.json(); allData = allData.concat(result.data || []); nextUrl = result?.paging?.next || null; if (nextUrl) { await delay(800); // Pause to avoid rate limits } } return allData.map(post => ({ id: post.brand_media_id, predicted_engagement: post.predictions?.engagement, actual_engagement: post.instagram?.engagement, post_url: post.instagram?.url })); } // Example usage: fetchPostMetrics({ brandId: 'your_brand_id', token: 'your_access_token', platform: 'INSTAGRAM_OWNED', startDate: '2024-01-01', endDate: '2024-12-31' }).then(data => console.log(data)); ``` **Step 1 — Configure the request** Set your `brandId`, `token`, `platform` (e.g. `INSTAGRAM_OWNED`), and date range via `source_created_at`. **Step 2 — Set up headers and a delay helper** Include the `Authorization` Bearer token and `Content-Type: application/json`. The delay helper adds a pause between paginated requests to respect rate limits. **Step 3 — Paginate through results** Send a `PUT` request and collect each page of results. If `paging.next` is present in the response, continue fetching until all pages are retrieved. **Step 4 — Shape the response** Map the raw response to only the fields you need — post ID, predicted engagement, actual engagement, and post URL — for clean integration into dashboards or reports. ## Sample response Each platform returns data in its own structure. When processing results, your integration should check the platform type and parse metrics accordingly. ```json Instagram theme={null} { "data": [ { "brand_id": "{brand_id}", "brand_media_id": 822392549, "caption_question": { "is_question": false, "user_overridden": false }, "caption_sentiment": { "is_negative": false, "is_neutral": true, "is_positive": false, "user_overridden": false }, "collections": null, "comment_sentiment": { "is_negative": false, "is_neutral": false, "is_positive": true }, "community_engagement": null, "content_tags": null, "created_at": "2025-04-28T17:30:48", "custom_metrics": [{"id": 78, "value": null}], "facebook": null, "id": 526519128, "instagram": { "caption": "Social media updates you might have missed this week", "comments_count": 1, "effectiveness": 0.024822695035460994, "emv": 473.083, "engagement": 0.0007613774009344178, "like_count": 18, "reach": 846, "saved": 2, "shares": 1, "sum_total_engagement": 22, "timestamp": "2025-04-28T17:30:29+00:00", "total_comments": 1, "total_likes": 18, "url": "https://www.instagram.com/p/DI_6vsqj/", "views": 1018 }, "source": "INSTAGRAM", "source_created_at": "2025-04-28T17:30:29", "source_type": "OWNED", "type": "IMAGE" } ], "paging": { "count": 8, "next": null, "previous": null } } ``` ```json Instagram Stories theme={null} { "data": [ { "brand_id": "{brand_id}", "brand_media_id": 823370801, "instagram": null, "instagram_story_frame": { "caption": null, "completion_rate": 0.794326, "completion_rate_views": 0.7972027972027972, "emv": 43.259, "exit_rate": 0.205674, "exits": 29, "hashtags": [], "reach": 141, "replies": 0, "taps_back": 12, "taps_forward": 120, "views": 141, "views_v2": 143 }, "source": "INSTAGRAM_STORY", "source_created_at": "2025-04-30T16:31:43", "source_type": "OWNED", "type": "IMAGE" } ], "paging": { "count": 35, "next": null, "previous": null } } ``` ```json Pinterest theme={null} { "data": [ { "brand_id": "{brand_id}", "brand_media_id": 764900017, "instagram": null, "pinterest": { "engagement_rate": 0.041666666666666664, "is_video": false, "link": "https://www.pinterest.com/pin/38066572", "note": "2024 Cross-Channel Social Media Benchmarks", "pin_board_name": "Digital Marketing Insights & Inspiration", "repins": 0, "title": "2024 Cross-Channel Social Media Benchmarks", "total_clicks": 2, "total_closeups": 5, "total_comments": 0, "total_impressions": 192, "total_saves": 1, "total_video_views": 0 }, "source": "PINTEREST", "source_created_at": "2024-03-25T18:38:36", "source_type": "OWNED", "type": "IMAGE" } ], "paging": { "count": 4, "next": null, "previous": null } } ``` ```json Facebook theme={null} { "data": [ { "brand_id": "{brand_id}", "brand_media_id": 822392539, "facebook": { "comments": 0, "engagement_rate": 0.0, "impressions": 100, "is_ad": false, "is_boosted": false, "link_clicks": 0, "message": "Social media updates you might have missed this week", "organic_engagements": 0, "organic_impressions": 100, "organic_reach": 99, "paid_and_organic_impressions": 100, "paid_and_organic_reach": 99, "reach": 99, "reactions": 0, "shares": 0, "total_engagements": 0, "type": "photo", "url": "https://www.facebook.com/508208781314605/posts/1255542963247846" }, "source": "FACEBOOK", "source_created_at": "2025-04-28T17:30:32", "source_type": "OWNED", "type": "IMAGE" } ], "paging": { "count": 6, "next": null, "previous": null } } ``` ```json X.com theme={null} { "data": [ { "brand_id": "{brand_id}", "brand_media_id": 813578171, "twitter": { "engagement_rate": 0.0, "engagements": 0, "impressions": 25, "impressions_organic": 25, "is_promoted": false, "likes": 0, "permalink_url": "https://twitter.com/185398/status/19093070442", "replies": 0, "retweets": 0, "text": "Post text here", "url_clicks": 0, "video_views": 0 }, "source": "TWITTER", "source_created_at": "2025-04-07T18:13:07", "source_type": "OWNED", "type": "IMAGE" } ], "paging": { "count": 5, "next": null, "previous": null } } ``` ```json TikTok theme={null} { "data": [ { "brand_id": "{brand_id}", "brand_media_id": 808465096, "tiktok": { "average_completion_rate": 0.573346385120962, "average_time_watched": 4.1, "caption": "Got THE shot", "comments": 1, "duration": 7.151, "effectiveness": 1.2400497512437811, "engagement_rate": 0.046019900497512436, "full_video_watched_rate": 0.1466, "impressions_for_you_rate": 0.827, "impressions_search_rate": 0.076, "likes": 34, "reach": 804, "shares": 2, "total_engagements": 37, "total_time_watched": 3941.0, "views": 960 }, "source": "TIKTOK", "source_created_at": "2025-03-26T15:45:34", "source_type": "OWNED", "type": "IMAGE" } ], "paging": { "count": 14, "next": null, "previous": null } } ``` ```json YouTube theme={null} { "data": [ { "brand_id": "{brand_id}", "brand_media_id": 795913920, "youtube": { "avg_view_duration": 161, "avg_view_percentage": 0.1877, "caption": "Dash Social - GDI Compliance Walkthrough", "comments": 0, "dislikes": 0, "duration": 861.0, "engagements": 0, "est_seconds_watched": 2220, "is_short": false, "likes": 0, "shares": 0, "subscribers": 491, "title": "Dash Social - GDI Compliance Walkthrough", "views": 14, "youtube_link": "https://www.youtube.com/watch?v=BL8eYHO0" }, "source": "YOUTUBE", "source_created_at": "2025-02-26T20:08:57", "source_type": "OWNED", "type": "IMAGE" } ], "paging": { "count": 1, "next": null, "previous": null } } ``` ## Metrics Select a platform to see the available metric names and their corresponding API key names. | Metric name | API key name | | ---------------------------------------- | ----------------------------------- | | Amount Spent - Promoted | `amount_spent` | | Clicks - Promoted | `clicks` | | Cost Per ThruPlay - Promoted | `cost_per_thruplay` | | CPC - Promoted | `cpc` | | CPM - Promoted | `cpm` | | CTR - Promoted | `ctr` | | Effectiveness - Organic | `effectiveness` | | Engagement Rate - Organic (Impressions) | `engagement_rate_impressions` | | Engagement Rate - Organic (Followers) | `engagement_rate_public` | | Entertainment Score | `entertainment_score` | | Impressions - Organic | `impressions` | | Likes - Organic | `like_count` | | LikeShop Clicks | `likeshop.clicks` | | Reach - Total | `paid_and_organic_reach` | | Saves - Total | `paid_and_organic_saved` | | Shares - Total | `paid_and_organic_shares` | | Engagement Rate - Promoted (Impressions) | `paid_engagement_rate` | | Impressions - Promoted | `paid_impressions` | | Likes - Promoted | `paid_likes` | | Reach - Promoted | `paid_reach` | | Saves - Promoted | `paid_saved` | | Shares - Promoted | `paid_shares` | | Video Views - Promoted | `paid_video_views` | | Bio Link Clicks - Organic | `profile_activity.bio_link_clicked` | | Calls - Organic | `profile_activity.calls` | | Directions - Organic | `profile_activity.direction` | | Emails - Organic | `profile_activity.email` | | Other - Organic | `profile_activity.other` | | Profile Clicks - Organic | `profile_activity.total` | | Profile Visits - Organic | `profile_visits` | | Reach - Organic | `reach` | | Replays - Organic | `replays` | | Saves - Organic | `saved` | | Shares - Organic | `shares` | | Engagements - Total | `sum_total_engagements` | | ThruPlays - Promoted | `thruplays` | | Comments - Total | `total_comments` | | Engagements | `total_engagement` | | Impressions - Total | `total_impressions` | | Likes - Total | `total_likes` | | All Plays - Organic | `total_plays` | | Total Time Viewed - Organic | `total_time_viewed_sec` | | Plays - Total | `total_video_views` | | Video Plays 100% - Promoted | `video_plays_100` | | Video Plays 25% - Promoted | `video_plays_25` | | Video Plays 50% - Promoted | `video_plays_50` | | Video Plays 75% - Promoted | `video_plays_75` | | Views | `views` | | Metric name | API key name | | --------------- | ----------------- | | Completion Rate | `completion_rate` | | EMV | `emv` | | Exit Rate | `exit_rate` | | Exits | `exits` | | Reach | `reach` | | Replies | `replies` | | Link Clicks | `swipe_up_link` | | Taps Back | `taps_back` | | Taps Forward | `taps_forward` | | Views | `views_v2` | | Metric name | API key name | | --------------------------- | ------------------------------------ | | Amount Spent | `amount_spend` | | Comments - Total | `comments` | | Cost Per ThruPlay | `cost_per_thruplays` | | CPC | `cpc` | | CPM | `cpm` | | CTR | `ctr` | | Frequency | `frequency` | | Comments - Organic | `organic_comments` | | Effectiveness - Organic | `organic_effectiveness` | | Engagement Rate - Organic | `organic_engagement_rate` | | Engagements - Organic | `organic_engagements` | | Impressions - Organic | `organic_impressions` | | Link Clicks - Organic | `organic_link_clicks` | | Reach - Organic | `organic_reach` | | Reactions - Organic | `organic_reactions` | | Shares - Organic | `organic_shares` | | Video Complete Views | `organic_video_complete_views` | | Video Views - Organic | `organic_video_views` | | Other Clicks | `other_clicks` | | Impressions - Total | `paid_and_organic_impressions` | | Photo View Clicks | `paid_and_organic_photo_view_clicks` | | Reach - Total | `paid_and_organic_reach` | | Reactions - Total | `paid_and_organic_reactions` | | Shares - Total | `paid_and_organic_shares` | | Video Views - Total | `paid_and_organic_video_views` | | Comments - Promoted | `paid_comments` | | Effectiveness - Promoted | `paid_effectiveness` | | Engagement Rate - Promoted | `paid_engagement_rate` | | Engagements - Promoted | `paid_engagements` | | Impressions - Promoted | `paid_impressions` | | Link Clicks - Promoted | `paid_link_clicks` | | Reach - Promoted | `paid_reach` | | Reactions - Promoted | `paid_reactions` | | Shares - Promoted | `paid_shares` | | Video Plays 100% - Promoted | `paid_video_complete_views` | | Video Views - Promoted | `paid_video_views` | | Post Clicks | `post_clicks` | | Effectiveness - Reels | `reel.effectiveness` | | Replays | `reel.fb_reels_replay_count` | | Total Plays | `reel.fb_reels_total_plays` | | Unique Impressions | `reel.post_impressions_unique` | | Avg. Time Watched | `reel.post_video_avg_time_watched` | | Follows | `reel.post_video_followers` | | Total Time Watched | `reel.post_video_view_time` | | Engagements - Total | `total_engagements` | | Video Plays 25% - Promoted | `video_plays_25` | | Video Plays 50% - Promoted | `video_plays_50` | | Video Plays 75% - Promoted | `video_plays_75` | | Metric name | API key name | | ----------------- | --------------------- | | Engagement Rate | `engagement_rate` | | Total Engagements | `engagements` | | User Follows | `follows` | | Impressions | `impressions` | | Likes | `likes` | | Quote Posts | `quote_tweets` | | Replies | `replies` | | Total Reposts | `retweets` | | Link Clicks | `url_clicks` | | Profile Clicks | `user_profile_clicks` | | Video Views | `video_views` | | Metric name | API key name | | -------------------------- | ----------------------------------- | | Location | `audience_locations` | | Avg. Time Watched | `average_time_watched` | | Comments | `comments` | | Video Duration | `duration` | | EMV | `emv` | | Engagement Rate | `engagement_rate` | | Entertainment Score | `entertainment_score` | | Completion Rate | `full_video_watched_rate` | | Retention Rate | `impressions_follow_rate` | | Traffic - For You Page | `impressions_for_you_rate` | | Traffic - Hashtag | `impressions_hashtag_rate` | | Traffic - Personal Profile | `impressions_personal_profile_rate` | | Traffic - Search | `impressions_search_rate` | | Traffic - Sound | `impressions_sound_rate` | | Likes | `likes` | | LikeShop Clicks | `likeshop.tiktok_clicks` | | Reach | `reach` | | Shares | `shares` | | Total Engagements | `total_engagements` | | Total Time Watched | `total_time_watched` | | Video Views | `views` | | Metric name | API key name | | ---------------------- | -------------------------- | | Avg. View Duration | `avg_view_duration` | | Avg. Percentage Viewed | `avg_view_percentage` | | Comments | `comments` | | Dislikes | `dislikes` | | Total Engagements | `engagements` | | Watch Time | `est_seconds_watched` | | Likes | `likes` | | Shares | `shares` | | Subscribers | `subscribers` | | Added To Playlist | `videos_added_to_playlist` | | Video Views | `views` | # Track analytics with the Content Tag API Source: https://developer.dashsocial.com/guides/reporting/track-analytics-with-content-tag-api Group posts by campaign, product, or theme using content tags and track performance across brands. Use the Content Tag API to group posts by campaign, product, or theme across multiple brands—then track performance by tag. ## Use case You're launching a lipstick campaign across four brands. Create a "Lipstick" tag, apply it via automation, and report on engagement across all related posts. ## Implementation ### Before you start You'll need: * API Key * Brand IDs * Organization 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. [Get started with the API →](https://developer.dashsocial.com/guides/get-started/quickstart) ### Step 1: Creating a content tag **Already have a Content Tag?** Skip this step and jump to Step 2. Start by creating a tag to group your campaign content. This lets you later filter and report on posts that share the same theme, product, or time frame. ```http theme={null} POST https://library-backend.dashsocial.com/organizations/{organization_id}/content_tags body = { "name": "Lipstick", "brand_ids": [ 1000, 1001, 1002, 1003 ] } ``` #### Key query parameters * `organization_id`: Your org's unique ID (ask your account manager if unsure) * `name`: Name of the tag (e.g., "Lipstick") * `brand_ids`: Array of brand IDs to apply this tag to Sample response: ```json theme={null} { "brand_ids": [ 1000, 1001, 1002, 1003 ], "created_at": "2025-03-07T15:48:45+00:00", "id": 3817, "name": "Lipstick", "organization_id": 1, "updated_at": "2025-03-07T15:48:45+00:00" } ``` ### Step 2: Retrieving content tags Use this endpoint to list all your content tags. Useful for confirming tag names or getting tag IDs for reporting: ```http theme={null} GET https://library-backend.dashsocial.com/organizations/{organization_id}/content_tags ``` #### Key query parameters * `organization_id`: Your organization's unique ID. Sample response: ```json theme={null} [ { "brand_ids": [ 1000, 1001, 1002, 1003 ], "created_at": "2025-01-26T08:20:44+00:00", "id": 3816, "name": "2025", "organization_id": 1, "updated_at": "2025-01-26T08:20:44+00:00" } { "brand_ids": [ 1000, 1001, 1002, 1003 ], "created_at": "2025-03-07T15:48:45+00:00", "id": 3817, "name": "Lipstick", "organization_id": 1, "updated_at": "2025-03-07T15:48:45+00:00" } ] ``` ### Step 3: Auto-tag posts Use [Content Automation](https://help.dashsocial.com/hc/en-us/articles/31114279045389-How-to-Set-Up-and-Manage-Content-Automation) to apply tags based on rules (e.g., hashtags, captions). ### Step 4: Get post level metrics Use this query to get a list of posts that have specific tags, along with metrics like impressions, likes, or comments. Ideal for reviewing individual post performance: ```http theme={null} PUT https://library-backend.dashsocial.com/brands/{brand_id}/media/v2 body = { "filters": { "content_tags": ["Lipstick", "2025"] }, "limit": 99, "offset":0 } ``` #### Key query parameters * `brand_id`: Brand ID you're querying * `content_tags`: Tags to filter by (e.g., `["Lipstick", "2025"]`) * `limit`: Max results per page (default 99) * `offset`: Pagination offset. Sample response: ```json theme={null} { "data": [ { "brand_id": 1000, "brand_media_id": 796350589, "caption_question": { "is_question": false, "user_overridden": false }, "caption_sentiment": { "is_negative": false, "is_neutral": true, "is_positive": false, "user_overridden": false }, "comment_sentiment": null, "community_engagement": null, "content_tags": [ "A test content tag" ], "created_at": "2025-02-27T17:16:56", "custom_metrics": [ { "id": 78, "value": null } ], "facebook": null, "id": 506593868, "image": { "sizes": { "medium_square": { "height": 640, "url": "https://images.dashsocial.com/aHR0cHM6Ly9jZG4uZGFzaHNvY2lhbC5jb20vbWVkaWEvZnVsbC8xNzQwNjc2NjE0LjgzODM2MTU5MTE5MC5qcGVn.jpg?w=640&h=640&fit=cover", "width": 640 }, "original": { "height": 1024, "size": 213914, "url": "https://cdn.dashsocial.com/media/original/1740676614.732703492652.jpg", "width": 1024 }, "original_converted": { "height": 1024, "size": 209493, "url": "https://cdn.dashsocial.com/media/full/1740676614.838361591190.jpeg", "width": 1024 }, "small": { "height": 400, "url": "https://images.dashsocial.com/aHR0cHM6Ly9jZG4uZGFzaHNvY2lhbC5jb20vbWVkaWEvZnVsbC8xNzQwNjc2NjE0LjgzODM2MTU5MTE5MC5qcGVn.jpg?w=400&h=400", "width": 400 }, "small_square": { "height": 400, "url": "https://images.dashsocial.com/aHR0cHM6Ly9jZG4uZGFzaHNvY2lhbC5jb20vbWVkaWEvZnVsbC8xNzQwNjc2NjE0LjgzODM2MTU5MTE5MC5qcGVn.jpg?w=400&h=400&fit=cover", "width": 400 } } }, "instagram": { "ad_ids": null, "adset_ids": null, "amount_spent": null, "avg_time_viewed_sec": null, "campaign_ids": null, "caption": "", "clicks": null, "comments_count": 0, "cost_per_thruplay": null, "cpc": null, "cpm": null, "ctr": null, "effectiveness": 0.0, "emv": 300.32, "engagement": 0.0, "engagement_rate_impressions": 0.0, "engagement_rate_public": 0.0, "entertainment_score": null, "followers_gained": null, "follows": null, "hashtags": [], "impressions": 0, "is_boosted": false, "is_carousel": true, "is_commented": false, "is_mentioned": false, "is_riq": false, "is_tagged": false, "like_count": 0, "paid_and_organic_reach": 0, "paid_and_organic_saved": 0, "paid_and_organic_shares": 0, "paid_comments": 0, "paid_engagement_rate": 0.0, "paid_impressions": 0, "paid_likes": 0, "paid_reach": null, "paid_reactions": null, "paid_saved": 0, "paid_shares": null, "paid_total_engagement": 0, "paid_total_engagements": 0, "paid_video_views": null, "photo_tags": [], "post_type": "carousel", "profile_activity": { "bio_link_clicked": 0, "direction": 0, "email": 0, "other": 0, "text": 0, "total": 0 }, "profile_visits": null, "reach": 0, "replays": null, "saved": 0, "shares": 0, "sum_total_engagement": 0, "sum_total_engagements": 0, "thruplays": null, "timestamp": "2025-02-27T17:15:54+00:00", "total_comments": 0, "total_engagement": 0, "total_impressions": 0, "total_likes": 0, "total_plays": null, "total_time_viewed_sec": null, "total_video_views": null, "url": "https://www.instagram.com/p/DGlV4j3z_K7/", "video_plays_100": null, "video_plays_25": null, "video_plays_50": null, "video_plays_75": null, "video_views": null, "views": 1 }, "instagram_ads": null, "instagram_story_frame": null, "likeshop": { "clicks": 0, "links": null, "tiktok_clicks": null }, "linkedin": null, "meta": {}, "pinterest": null, "predictions": { "engagement": 0.0272196 }, "source": "INSTAGRAM", "source_created_at": "2025-02-27T17:15:54", "source_id": "17875851276184969", "source_type": "OWNED", "threads": null, "tiktok": null, "twitter": null, "type": "CAROUSEL", "youtube": null } ], "paging": { "count": 1, "next": null, "previous": null } } ``` ### Step 5: Get aggregated metrics Use this endpoint to pull total engagement data for all posts with a given tag—across brands and platforms. Great for high-level campaign reporting. ```http theme={null} GET https://dashboard.dashsocial.com/reports/data? brand_ids=1000,1001,1002 &start_date=2025-01-01 &end_date=2025-03-07 &context_start_date=2025-01-01 &context_end_date=2025-03-07 &channels=FACEBOOK &metrics=TOTAL_ENGAGEMENTS &content_tag_ids=3817,3818 ``` ### Key query parameters * `brand_ids`: Comma-separated brand IDs (e.g., 1000,1001) * `start_date`,`end_date`: Reporting period. * `context_start_date`,`context_end_date`: Comparison period (optional) * `channels`: Social media channel (e.g., "FACEBOOK") * `metrics`: Metric types (e.g., TOTAL\_ENGAGEMENTS) * `content_tag_ids`: Filter by tag IDs. This can be retrieved from [Step 2: Retrieving all content tags](#step-2-retrieving-content-tags) # Schedule Social Media Posts with the Dash API Source: https://developer.dashsocial.com/guides/scheduler/schedule-social-media-posts-with-the-dash-api Learn how to schedule social media posts across supported platforms using the Dash API. # Overview This guide shows you how to create and manage scheduled social media posts across supported platforms using the Dash API. You can publish posts immediately, schedule them for a future time, or save them as drafts. This allows you to automate content publishing directly from your own tools or workflows. ## Supported Platforms The Scheduler API supports the following platforms: * Instagram * Facebook * TikTok * YouTube * X * Threads * LinkedIn * Snapchat * Pinterest * Bluesky # Use Case You can use the scheduling API to automate and manage social publishing directly from your own tools. Schedule posts across multiple platforms from your internal CMS or content calendar. This allows marketing teams to plan campaigns without using the Dash UI. Queue posts to publish at exact times during launches, events, or announcements. Posts can be scheduled days or weeks in advance. Save posts as drafts so teams can review content before publishing. Programmatically schedule large batches of posts across platforms, useful for agencies or large content pipelines. # Before You Start You'll need: * **API Key**: Get this from the Dash Social **Developer** section * **Brand ID**: Available in your developer settings or next to your brand name in the platform See more details here: Make your first API call in less than a minute and confirm your API key is working. # Scheduling Workflow Scheduling a post with the Dash API follows three steps: 1. **Upload media** to the Dash Library 2. **Create a scheduled post** for the platform 3. **Manage the post** using the returned `id` from the scheduler response ```mermaid theme={null} flowchart TD A["Upload Media (optional)"] --> B["Create Scheduled Post"] B --> C["Receive id"] C --> D["Retrieve / Update / Delete Post"] ``` # Key Concepts ### Scheduler `id` * Returned when a scheduled post is created * Used to retrieve, update, or delete the post ### `status` Defines how the post should behave. | Status | Behavior | | ---------------- | ------------------------------------------- | | `AUTOPUBLISHING` | Post is set to publish immediately | | `SCHEDULED` | Post publishes at the specified `timestamp` | | `DRAFT` | Post is saved as a draft | ### `auto_publish` Controls whether the post will publish automatically or require manual publishing. | Value | Behavior | | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `true` | The post will automatically publish at the scheduled time. | | `false` | The post will not publish automatically. Users associated with the brand will receive a push notification in the Dash mobile app reminding them to publish the post. | Some fields are not available when `auto_publish` is disabled because they only work with automatic publishing: * `first_comment` is not supported for Instagram and Facebook when `auto_publish` is disabled. ### `media_id` * Returned when media is uploaded to Dash * Used when attaching image or video media to a post * When scheduling a post, include this value inside the `media_ids` array * Required for some platforms, post types, and auto-publish posts * Not required for supported caption-only posts or some draft posts without media ## Media Requirements by Platform Media requirements vary by platform and post type. | Platform | Caption-only Post | Draft Without Media | Media Requirements | | --------- | ----------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------ | | Instagram | ❌ | ✅ | `POST`, `REEL`, and `STORY` drafts can be created without media. Auto-publish posts require `media_ids`. | | TikTok | ❌ | ✅ | Drafts can be created without media. Auto-publish posts require **video media**. | | Facebook | ✅ | ✅ | Standard `POST` can be caption-only. `REEL` requires **video media**. | | X | ✅ | ✅ | Caption-only posts are supported. | | Threads | ✅ | ✅ | Caption-only posts are supported. | | LinkedIn | ✅ | ✅ | Caption-only posts are supported. | | YouTube | ❌ | ❌ | Requires **video media**. | | Snapchat | ❌ | ❌ | `STORY` requires image or video. `SPOTLIGHT` requires **video media**. | | Pinterest | ✅ | ✅ | Drafts can be created without media. Auto-publish posts require media. `title` and a Pinterest board are required. | | Bluesky | ✅ | ✅ | Caption-only posts are supported. Image posts support up to **4 images**. Mixed media and video are not supported. |
## Media Support by Platform Some platforms support multiple media items or mixed media types, while others require a single media asset. | Platform | Media Types | Media Count | Mixed Media | Notes | | ------------------ | ------------ | ----------------------------------- | ----------- | ------------------------------------------------------------------------------------------- | | Instagram Post | Image, Video | Up to 10 | ✅ | Supports mixed media (images and videos in the same post). | | Instagram Reel | Video | 1 | ❌ | Reels only support a single video. | | Instagram Story | Image, Video | 1 auto-publish, multiple for drafts | ❌ | Multiple media can only be saved as drafts. Auto-publish posts support a single media item. | | TikTok | Video | 1 | ❌ | TikTok posts must contain a single video. | | Facebook Post | Image, Video | Up to 10 images or 1 video | ❌ | Images and videos cannot be mixed. | | Facebook Reel | Video | 1 | ❌ | Reels must contain a single video. | | LinkedIn | Image, Video | 20 images or 1 video | ❌ | Image posts support 20 images. Video posts support only one video. | | YouTube | Video | 1 | ❌ | YouTube posts must contain a single video. | | Threads | Image | 20 | ❌ | Threads currently supports multiple images only. | | X | Image, Video | Up to 4 images or 1 video | ❌ | Images and videos cannot be mixed. | | Snapchat Story | Image, Video | 1 | ❌ | Stories support either image or video. | | Snapchat Spotlight | Video | 1 | ❌ | Spotlight posts must contain a single video. | | Pinterest | Image, Video | 1 | ❌ | Pins support a single image or a single video. Mixed media is not supported. | | Bluesky | Image | Up to 4 | ❌ | Bluesky supports image posts only. Mixed media and video are not supported. | ## Publishing Modes Most platforms support three publishing behaviors. | Mode | `status` | `auto_publish` | `timestamp` | | :------------------ | :--------------- | :---------------- | :----------- | | Publish Immediately | `AUTOPUBLISHING` | `true` | Not required | | Schedule for Later | `SCHEDULED` | `true` | Required | | Save as Draft | `DRAFT` | `true` or `false` | Optional | **Note** * Some platforms do not support `auto_publish: false`. * LinkedIn, Snapchat and YouTube require `auto_publish: true`. * Threads and Bluesky always publish with `auto_publish: true`, even if `false` is provided (the value is ignored). * `status` controls the **state of the post** (draft, scheduled, or publishing immediately). * `auto_publish` controls the **publishing method** (auto-publish vs. send notification / publish via mobile). * A post with `status: "DRAFT"` can be created with either `auto_publish: true` or `false`, depending on platform support. ## Platform Comparison | Platform | Endpoint | Caption Field | Media Types | Special Fields | | --------- | ---------------------------- | ---------------------- | ------------ | --------------------------------------------------- | | Instagram | `/instagram/scheduled_posts` | `caption` | Image, Video | `post_type`, `first_comment` | | X | `/twitter/scheduled_posts` | `tweet_status` | Image, Video | — | | Facebook | `/facebook/scheduled_posts` | `message` | Image, Video | `post_type`,`first_comment`, `link` | | TikTok | `/tiktok/scheduled_posts` | `text` | Video only | `disable_comment`, `disable_duet`, `disable_stitch` | | Threads | `/threads/scheduled_posts` | `text` | Image, Video | — | | LinkedIn | `/linkedin/scheduled_posts` | `text` | Image, Video | — | | YouTube | `/youtube/scheduled_posts` | `title`, `description` | Video only | `declared_made_for_kids` | | Snapchat | `/snapchat/scheduled_posts` | `description` | Image, Video | `post_type`, `save_to_profile`, `locale` | | Pinterest | `/pinterest/scheduled_posts` | `note` | Image, Video | `meta.title`, `meta.pinterestBoard`, `link` | | Bluesky | `/bluesky/scheduled_posts`\* | `text` | Image only | — | # Implementation ## Step 1: Upload Media (optional) If your post includes images or videos, upload the media to the Dash Library first. This returns a `media_id` that you can include when creating the scheduled post. If your post does not include media (for example, a text-only or link-based post), you can skip this step. [Jump to Step 2](#step-2-create-a-scheduled-post) ```http theme={null} POST https://library-backend.dashsocial.com/brands/{brand_id}/media body: { "source": "UPLOAD", "source_id": "your-internal-id", "type": "UPLOADED", "url": "https://example.com/media.jpg", "meta": "{ \"filename\": \"filename.jpg\" }", "source_created_at": "2026-03-06T12:00:00Z" } ``` See more about this step here: Upload media directly from your CMS to your Dash Social Library ### Response ```json theme={null} { "ai_alternatives": [], "brand_id": 144, "campaigns": [], "caption_question": null, "caption_sentiment": null, "content_tags": [], "created_at": "2026-03-06T22:21:57+00:00", "duration": null, "elastic_search_index_status": null, "frame_rate": null, "galleries": [], "hide_in_widget": false, "id": 950680003, "image_sizes": { "medium_square": { "height": 640, "url": "https://images.dashsocial.com/aHR0cHM6Ly9jZG4uZGFzaHNvY2lhbC5jb20vbWVkaWEvZnVsbC8xNzcyODM1NzE2LjQzMTc0NDY3NDIzMi5qcGVn.jpg?w=640&h=640&fit=cover", "width": 640 }, "original": { "height": 534, "size": 72890, "url": "https://cdn.dashsocial.com/media/original/1772835716.24373761829.jpg", "width": 800 }, "original_converted": { "height": 534, "size": 72992, "url": "https://cdn.dashsocial.com/media/full/1772835716.431744674232.jpeg", "width": 800 }, "small": { "height": 400, "url": "https://images.dashsocial.com/aHR0cHM6Ly9jZG4uZGFzaHNvY2lhbC5jb20vbWVkaWEvZnVsbC8xNzcyODM1NzE2LjQzMTc0NDY3NDIzMi5qcGVn.jpg?w=599&h=400", "width": 599 }, "small_square": { "height": 400, "url": "https://images.dashsocial.com/aHR0cHM6Ly9jZG4uZGFzaHNvY2lhbC5jb20vbWVkaWEvZnVsbC8xNzcyODM1NzE2LjQzMTc0NDY3NDIzMi5qcGVn.jpg?w=400&h=400&fit=cover", "width": 400 } }, "likeshop_clicks": null, "media_group": null, "media_id": 647749496, "media_type": "IMAGE", "meta": {}, "original_height": "534", "original_width": "800", "predictions": {}, "source": "UPLOAD", "source_created_at": "2026-03-06T12:00:00+00:00", "source_data": { "avatar_url": null, "first_name": "sept 9 test", "last_name": "API" }, "source_id": "NATGEO", "status": 2, "system_tags": [], "tags": [], "tiktok_likeshop_clicks": null, "triggered_content_automations": [], "type": "UPLOADED", "updated_at": "2026-03-06T22:21:57+00:00", "urls": { "640": "https://images.dashsocial.com/aHR0cHM6Ly9jZG4uZGFzaHNvY2lhbC5jb20vbWVkaWEvZnVsbC8xNzcyODM1NzE2LjQzMTc0NDY3NDIzMi5qcGVn.jpg?w=640&h=640&fit=cover", "full": "https://cdn.dashsocial.com/media/full/1772835716.431744674232.jpeg", "original": "https://cdn.dashsocial.com/media/original/1772835716.24373761829.jpg", "ratio": "https://images.dashsocial.com/aHR0cHM6Ly9jZG4uZGFzaHNvY2lhbC5jb20vbWVkaWEvZnVsbC8xNzcyODM1NzE2LjQzMTc0NDY3NDIzMi5qcGVn.jpg?w=599&h=400", "thumbs": "https://images.dashsocial.com/aHR0cHM6Ly9jZG4uZGFzaHNvY2lhbC5jb20vbWVkaWEvZnVsbC8xNzcyODM1NzE2LjQzMTc0NDY3NDIzMi5qcGVn.jpg?w=400&h=400&fit=cover" }, "video_conversion_warnings": null, "video_sizes": {} } ``` Save the returned `media_id`. You'll include this value in `media_ids` when creating the scheduled post. ## Step 2: Create a Scheduled Post This API can **publish posts directly to your social media accounts**. Posts with `auto_publish: true` will automatically publish at the scheduled time. Test with drafts or a test account before publishing to live channels. When creating a scheduled post, include `media_ids` only when required by the platform or post type. Some platforms support caption-only or link-based posts without media, while others require media for all posts or for auto-publish posts. ### Instagram Use this endpoint to schedule feed posts, stories, or reels. #### Endpoint ```http theme={null} POST https://scheduler.dashsocial.com/instagram/scheduled_posts?media_v2=true ``` #### Request ```json theme={null} { "auto_publish": true, "brand_id": 144, "status": "SCHEDULED", "caption": "Launching our new product today!", "first_comment": "Let us know what you think 👇", "media_ids": [621242772], "post_type": "FEED", "timestamp": "2026-03-10T15:00:00Z" } ``` #### Instagram Fields | Parameter | Description | | --------------- | ----------------------------------------------------------------- | | `post_type` | Required. Available value:`FEED`, `STORY`, or `REEL` | | `caption` | Post caption | | `first_comment` | Optional first comment (not supported when `auto_publish: false`) | **Notes** * `post_type` determines whether the post is a `FEED`, `STORY`, or `REEL`. * `first_comment` is not supported when `auto_publish` is `false`. * Auto-publish posts must include media. ### X (Twitter) #### Endpoint ```http theme={null} POST https://scheduler.dashsocial.com/twitter/scheduled_posts?media_v2=true ``` #### Request ```json theme={null} { "auto_publish": true, "brand_id": 144, "status": "SCHEDULED", "timestamp": "2026-03-10T15:00:00Z", "tweet_status": "Launching something new today 🚀" } ``` #### X Fields | Parameter | Description | | -------------- | ----------- | | `tweet_status` | Tweet text | **Note** * Standard X posts support up to **280 characters**. * Accounts with **X Premium** can publish posts up to **25,000 characters**. ### Facebook #### Endpoint ```http theme={null} POST https://scheduler.dashsocial.com/facebook/scheduled_posts?media_v2=true ``` #### Request ```json theme={null} { "auto_publish": true, "brand_id": 144, "status": "SCHEDULED", "message": "Check out our newest launch!", "media_ids": [621242772], "timestamp": "2026-03-10T15:00:00Z", "first_comment": "Drop your thoughts below!", "post_type":"POST" } ``` #### Facebook Fields | Parameter | Description | | --------------- | ----------------------------------------------------------------- | | `post_type` | Required. Available value:`POST` or `REEL` | | `message` | Post caption | | `first_comment` | Optional first comment (not supported when `auto_publish: false`) | | `link` | Optional link preview | **Notes** * Standard `POST` can be created without media. * `REEL` posts require **video media**. * `first_comment` is not supported when `auto_publish` is `false`. ### TikTok TikTok only supports **video uploads**. #### Endpoint ```http theme={null} POST https://scheduler.dashsocial.com/tiktok/scheduled_posts?media_v2=true ``` #### Request ```json theme={null} { "auto_publish": true, "brand_id": 144, "status": "SCHEDULED", "text": "Behind the scenes of our launch", "media_ids": [621242772], "timestamp": "2026-03-10T15:00:00Z", "disable_comment": false, "disable_duet": false, "disable_stitch": false } ``` #### TikTok Fields | Parameter | Description | | ----------------- | ---------------------------------------------------------------------------- | | `text` | Caption for the TikTok post. | | `disable_comment` | Optional. Set to `true` to disable comments on the post. | | `disable_duet` | Optional. Set to `true` to prevent users from creating duets with the video. | | `disable_stitch` | Optional. Set to `true` to prevent users from stitching the video. | **Notes** * TikTok posts require **video media** for auto-publish. * Only **one video** can be attached to a TikTok post. ### Threads #### Endpoint ```http theme={null} POST https://scheduler.dashsocial.com/threads/scheduled_posts?media_v2=true ``` #### Request ```json theme={null} { "auto_publish": true, "brand_id": 144, "status": "SCHEDULED", "text": "Something exciting is coming.", "media_ids": [621242772], "timestamp": "2026-03-10T15:00:00Z" } ``` **Notes** * `auto_publish` is always treated as `true`. * Threads supports caption-only posts. * Multiple images can be attached to a post. ### LinkedIn #### Endpoint ```http theme={null} POST https://scheduler.dashsocial.com/linkedin/scheduled_posts?media_v2=true ``` #### Request ```json theme={null} { "auto_publish": true, "brand_id": 144, "status": "SCHEDULED", "text": "We're excited to share our newest launch.", "media_ids": [621242772], "timestamp": "2026-03-10T15:00:00Z" } ``` **Notes** * `auto_publish: false` is not supported. * LinkedIn supports caption-only posts. * Image posts can include multiple images, but video posts support **one video only**. ### YouTube YouTube supports **video uploads only**. #### Endpoint ```http theme={null} POST https://scheduler.dashsocial.com/youtube/scheduled_posts?media_v2=true ``` #### Request ```json theme={null} { "auto_publish": true, "brand_id": 144, "status": "SCHEDULED", "title": "Product Launch", "description": "Watch our newest launch announcement.", "media_ids": [621242772], "timestamp": "2026-03-10T15:00:00Z", "declared_made_for_kids": "false" } ``` #### YouTube Fields | Parameter | Description | | ------------------------ | -------------------------------------------------------------------------------------------------- | | `title` | **Required**. Title of the YouTube video. | | `description` | Optional description for the video. | | `declared_made_for_kids` | Required. Indicates whether the content is made for kids (`true` or `false`) for COPPA compliance. | **Notes** * `auto_publish: false` is not supported. * `media_ids` is required for YouTube posts. * Only **one video** can be attached to a post. * The video must be uploaded to the Dash Library before scheduling. ### Snapchat Snapchat supports two post types: * **Story** posts can use **image or video** media * **Spotlight** posts require a **video** #### Endpoint ```http theme={null} POST https://scheduler.dashsocial.com/snapchat/scheduled_posts?media_v2=true ``` **Story Request** Use `post_type: "STORY"` to create a Snapchat Story post. Note that post caption (`description`) is **not** available for Snapchat Story post. ```json theme={null} { "auto_publish": true, "brand_id": 144, "status": "SCHEDULED", "media_ids": [650029769], "timestamp": "2026-03-12T16:05:00.000Z", "post_type": "STORY" } ``` **Spotlight Request** Use `post_type: "SPOTLIGHT"` to create a Snapchat Spotlight post. Spotlight posts must use **video media**. ```json theme={null} { "brand_id": 144, "status": "SCHEDULED", "media_ids": [648771867], "timestamp": "2026-03-12T18:00:00.000Z", "description": "3 quick ways to style oversized sweaters this fall 🍂", "post_type": "SPOTLIGHT", "save_to_profile": true, "locale": "en_US" } ``` #### Snapchat Fields | Parameter | Description | | ----------------- | --------------------------------------------------------------------------------------- | | `post_type` | Required. Available values: `STORY` or `SPOTLIGHT`. | | `description` | Optional caption text for `SPOTLIGHT` posts. Not supported for `STORY` posts. | | `save_to_profile` | Boolean. Required for `SPOTLIGHT` posts. Saves the post to the public Snapchat profile. | | `locale` | Required for `SPOTLIGHT` posts. Locale for the post, for example `en_US`. | **Notes** * `auto_publish: false` is not supported. * `media_ids` is required for Snapchat posts. * `STORY` posts support image or video and do not support `description`. * `SPOTLIGHT` posts support video only. * `save_to_profile` and `locale` are required for `SPOTLIGHT` posts. ### Pinterest Pinterest scheduled posts require: * a valid **board ID** * a **title** * media for **auto-publish** posts Pinterest supports image and video Pins. A Pin can include only **1 media item**. #### Step 1: Get a Pinterest Board Before creating a Pinterest scheduled post, retrieve the available boards for the brand. ```http theme={null} GET https://pinterest.dashsocial.com/v5/brands/{brand_id}/boards ``` Response ```json theme={null} [ { "description": "", "id": "123456789012345678", "name": "Spring Style Inspiration", "preview_url": "https://example.com/board-preview.jpg", "protected": false } ] ``` Use the **entire board object** returned from this endpoint when creating the scheduler. #### Step 2: Create the Scheduled Post ```http theme={null} POST https://scheduler.dashsocial.com/pinterest/scheduled_posts?media_v2=true ``` Request ```json theme={null} { "auto_publish": true, "brand_id": 144, "status": "SCHEDULED", "media_ids": [650431494], "link": "https://example.com/products/linen-oversized-blazer", "meta": { "pinterestBoard": { "description": "", "id": "123456789012345678", "name": "Spring Style Inspiration", "preview_url": "https://example.com/board-preview.jpg", "protected": false }, "title": "Oversized Linen Blazer Outfit Ideas" }, "note": "Lightweight linen blazer styled three ways for spring. Perfect layering piece for everyday outfits.", "timestamp": "2026-03-12T20:45:00.000Z" } ``` #### Pinterest Fields | Parameter | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `meta.pinterestBoard` | Required. The Pinterest board where the Pin will be published. Include the **entire board object** returned from the boards endpoint. | | `meta.title` | Required. Title of the Pin. | | `note` | Optional description for the Pin. | | `link` | Optional destination URL for the Pin. | **Notes** * A valid Pinterest board is required to create a scheduled post. * `title` is required for all Pinterest posts. * Draft posts can be created **without media**. * Auto-publish posts **require media**. * Pinterest supports **image or video** Pins. * Pins support **1 media item only**. * When possible, link directly to the destination page. Pinterest may reject certain redirects or URL shorteners. ### Bluesky Bluesky supports caption-only posts and image posts. * Caption-only posts are supported * Image posts can include up to **4 images** * Video is not supported * Mixed media is not supported #### Endpoint ```http theme={null} POST https://scheduler.dashsocial.com/bluesky/scheduled_posts?media_v2=true ``` Request ```json theme={null} { "auto_publish": true, "brand_id": 144, "status": "SCHEDULED", "media_ids": [650431494, 650482495, 650419615, 650418969], "timestamp": "2026-03-12T22:30:00.000Z", "text": "A few recent favorites from our spring inspiration board." } ``` **Notes** * `auto_publish` is always treated as `true`. * Bluesky supports **caption-only posts**. * Image posts support up to **4 images**. * Bluesky supports **image media only**. * Mixed media and video are **not supported**. ## Scheduler Response Format Creating a scheduled post returns the scheduled post object. All platforms return the same core response structure, with some additional platform-specific fields depending on the channel. ### Common Response Fields | Field | Description | | ------------------- | ---------------------------------------------------------------------------------------- | | `id` | Unique ID of the scheduled post. Use this value to retrieve, update, or delete the post. | | `brand_id` | ID of the brand associated with the scheduled post. | | `status` | Current post status, such as `DRAFT`, `SCHEDULED`, or `AUTOPUBLISHING`. | | `auto_publish` | Indicates whether the post will publish automatically. | | `timestamp` | Scheduled publish time, if set. | | `media_ids` | Array of media IDs attached to the post. | | `media` | Expanded media objects attached to the post. | | `created_at` | Time the scheduled post was created. | | `updated_at` | Time the scheduled post was last updated. | | `approval_policy` | Approval policy applied to the post. | | `approval_status` | Current approval state of the post. | | `approval_requests` | Approval requests associated with the post. | ### Platform-Specific Fields Some platforms return additional fields in the response. For example: * Instagram may return fields such as `caption`, `first_comment`, and `post_type` * X may return `tweet_status` * Facebook may return `message`, `link`, and `post_type` * Pinterest may return `note`, `link`, and `meta` * Snapchat may return `description`, `post_type`, `save_to_profile`, and `locale` ### Example Response ```json theme={null} { "approval_policy": "APPROVAL_REQUIRED", "approval_requests": [], "approval_status": "UNASSIGNED", "auto_publish": true, "auto_publish_error": null, "brand_id": 144, "created_at": "2026-03-12T20:34:11.048341+00:00", "has_scheduled_time": true, "id": 806262, "live_post_url": null, "media": [ { "brand_id": 144, "created_at": "2026-03-12T18:00:12+00:00", "id": 650431494, "meta": { "filename": "example-image.png", "uploaded_by": 77315 }, "predictions": { "engagement": 0.278311 }, "source": "UPLOAD", "source_created_at": "2026-03-12T18:00:11+00:00", "source_id": "95987d98-7510-41f8-bacb-8683c7f7b0d5", "source_type": "OWNED", "type": "IMAGE", "updated_at": "2026-03-12T18:00:12+00:00", "variants": [] } ], "media_ids": [650431494], "status": "SCHEDULED", "timestamp": "2026-03-12T22:45:00+00:00", "updated_at": "2026-03-12T20:34:11.048344+00:00" } ```
## Manage Scheduled Posts Once a post is scheduled, you can retrieve, update, or delete it using the `id` returned from the response. ### Get All Scheduled Posts Retrieve all scheduled posts for a brand within a specified time range. ```http theme={null} GET https://scheduler.dashsocial.com/{platform}/scheduled_posts?brand_ids={brand_id}&start={start}&end={end}&sort=TIMESTAMP&media_v2=true ``` Example: ```http theme={null} GET https://scheduler.dashsocial.com/instagram/scheduled_posts?brand_ids=2000&start=2026-03-22T00:00:00&end=2026-03-28T23:59:59&sort=TIMESTAMP&media_v2=true ``` #### Query Parameters | Parameter | Description | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `brand_ids` | **Required**. The ID of the brand whose scheduled posts you want to retrieve. | | `start` | Recommended. Start of the date range (ISO 8601 format with timezone offset, for example `2026-03-22T00:00:00`). Omitting this may result in slow response times. | | `end` | Recommended. End of the date range (ISO 8601 format with timezone offset, for example `2026-03-28T23:59:59`). Omitting this may result in slow response times. | | `sort` | Sort order for results. Available values: `TIMESTAMP`, `UPDATED_AT`. Prefix with `-` for descending order (for example, `-TIMESTAMP`). | | `media_v2` | Set to `true` to returns media data in the current format. | **Notes** * Replace `{platform}` in the URL with the platform path for the channel you want to query. See the [Platform Comparison](#platform-comparison) table for the full list of endpoint paths. * `start` and `end` are optional but strongly recommended. Without them, the API will query all posts for the brand, which can result in slow response times. * Timezone offsets are supported in the `start` and `end` parameters. #### Query Parameters | Parameter | Description | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `brand_ids` | **Required**. The ID of the brand whose scheduled posts you want to retrieve. | | `start` | **Required**. Start of the date range (ISO 8601 format with timezone offset, for example `2026-03-22T00:00:00-04:00`). | | `end` | **Required**. End of the date range (ISO 8601 format with timezone offset, for example `2026-03-28T23:59:59-04:00`). | | `sort` | Sort order for results. Available values: `TIMESTAMP`, `UPDATED_AT`. Prefix with `-` for descending order (for example, `-TIMESTAMP`). | | `media_v2` | **Required**. Must be set to `true`. Returns media data in the current format. | **Notes** * Replace `{platform}` in the URL with the platform name (for example, `instagram`, `facebook`, `tiktok`). * `start` and `end` define the window of scheduled post timestamps to return. * Timezone offsets are supported in the `start` and `end` parameters. ### Get a Scheduled Post Retrieve the full details of a scheduled post. ```http theme={null} GET https://scheduler.dashsocial.com/{platform}/scheduled_posts/{id} ``` Example: ```http theme={null} GET https://scheduler.dashsocial.com/instagram/scheduled_posts/12345 ``` ### Update a Scheduled Post Use `PATCH` to update specific fields without replacing the entire post. ```http theme={null} PATCH https://scheduler.dashsocial.com/{platform}/scheduled_posts/{id}?media_v2=true body: { "caption": "Updated caption", "timestamp": "2026-03-12T15:00:00Z" } ``` Only the fields included in the request will be updated. ### Delete a Scheduled Post Remove a scheduled post so it will not be published. ```http theme={null} DELETE https://scheduler.dashsocial.com/{platform}/scheduled_posts/{id} ``` Example: ```http theme={null} DELETE https://scheduler.dashsocial.com/instagram/scheduled_posts/12345 ``` # Common Errors | Error | Cause | | ---------------------- | -------------------------------------------------- | | Invalid `media_id` | Media was not uploaded or belongs to another brand | | Missing `timestamp` | Required when `status = SCHEDULED` | | Unsupported media type | For example, using an image for TikTok | | Invalid platform field | Using the wrong caption parameter | # Final Outcome After completing this guide: * Your media is uploaded to Dash * Your post is scheduled for publishing * You receive an `id` in the scheduler response that you can use to manage the post later # Next Steps You can extend this workflow by: * Scheduling posts across multiple platforms * Automating content calendars * Retrieving scheduled posts for reporting * Building internal publishing tools using the Scheduler API # Automate Sending LikeShop Email Captures To CRMs Source: https://developer.dashsocial.com/guides/social-commerce/automate-sending-likeshop-email-captures-to-crms In this guide we will be going over the concept and API needed to automate importing emails captured from your brand's LikeShop so that you don't have to manually upload them to your email marketing tool such as MailChimp, Hubspot, etc. # Get up to speed quickly You will need two things to get started and make any Dash Social API calls: 1. **API Key:** Our API key (Bearer Token) can be generated directly from our platform under the Developer section. 2. **Brand ID:** You can see your `brand_id` next to your brand name under the Developer section as well. If you haven't done so already, check out the [API Quickstart guide](/guides/get-started/quickstart) to learn how you can get your `API Key` & `brand_id`. *** # Get emails from LikeShop Getting LikeShop emails in JSON is simple — start by calling `https://library-backend.dashsocial.com/brands/{brand_id}/galleries/likeshop/email_submissions` with your `brand_id`. | Parameter | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------ | | `brand_id` (REQUIRED) | The Dash Social assigned ID of the brand. | | `start_date` | string or null. Default: null. Example: `start_date=2019-12-01`. Filter results starting from a date in UTC. | | `end_date` | string or null. Default: null. Example: `end_date=2019-12-12`. Filter results ending at a date in UTC. | | `limit` | integer \[ 0 .. 5000 ]. Default: 2000. Number of results to return in a single response. | | `offset` | integer >= 0. Default: 0. The offset of the result to be returned. | ### Request Example ```http theme={null} GET https://library-backend.dashsocial.com/brands//galleries/likeshop/email_submissions?start_date=2022-11-20T18:00:00&end_date=2022-11-20T17:00:00 headers = { 'Authorization': 'Bearer ' } ``` You should expect a JSON response as below. ```json theme={null} { "data": [ { "captured_at": "2021-08-10T17:13:24", "email": "anonymous-2@dashsocial.com" }, { "captured_at": "2021-08-10T19:48:28", "email": "anonymous-3@dashsocial.com" } ], "paging": { "count": 2, "next": null, "previous": null } } ``` # Automation Concept For automation purposes you might want to take advantage of the date filters to get the latest emails captured — let's say in the last 1 hour. This number can be higher or lower, but we recommend not going under 10 mins. Let us know if you have any feedback. # Get started with Social Commerce Source: https://developer.dashsocial.com/guides/social-commerce/get-started-with-social-commerce Connect your product data and display shoppable galleries on your website with Dash Social. This guide provides an overview of the steps required to connect your product data and display product galleries on your website. Follow the steps in order for a smooth integration. ```mermaid theme={null} flowchart LR A[fa:fa-database Set Up Product Feed] --> B[fa:fa-images Choose Gallery Type] B --> C[fa:fa-th-large Shoppable Gallery] B --> D[fa:fa-box Product Page Gallery] B --> E[fa:fa-link Likeshop Gallery] C --> F[fa:fa-code Select Integration Method] D --> F E --> F F --> G[fa:fa-cogs JavaScript Widget] F --> H[fa:fa-code API Integration] G --> I[fa:fa-rocket Implement Gallery] H --> I ``` ## Implementation ### Step 1: Set up your product feed Before creating galleries, connect your product catalog to our system. This imports product details such as names, prices, images, and stock status. Set up a product feed to import and sync your product data in Dash. *** ### Step 2: Choose your gallery type After the product feed is set up, decide how you want to display your products. #### Shoppable Gallery A clickable, curated gallery that links social content to product pages. Best for homepages, landing pages, or editorial sections. #### Product Page Gallery A product-specific carousel or grid that displays user-generated or brand content for a single product. Best for product detail pages (PDPs). See more difference between Shoppable Gallery and Product Page Gallery here: Understand the differences between Shoppable and Product Page Galleries #### Likeshop Gallery A scrollable carousel or gallery that displays clickable posts from your LikeShop, linking Instagram and TikTok content directly to product pages. Best for creating a link-in-bio shopping experience that connects social traffic to your site. *** ### Step 3: Select an integration method There are two ways to add a gallery to your site: #### JavaScript Widget * Quick to deploy with a ready-made layout. * Minimal coding required. * Collects metrics such as views and click tracking automatically, displayed in Dash Social reports. * Best for teams that want an easy setup without developer support. #### API Integration * Full flexibility to create a custom gallery that matches your brand. * Avoids third-party JavaScript for stricter security and performance needs. * Cache content server-side for faster load times. * Integrate localized product data or other custom feeds. * Can be used to power both websites and native mobile apps. See more details here: API vs Widget: Which Integration to Use. *** ### Step 4: Implement your gallery Follow the instructions for your selected gallery type and integration method. #### Shoppable Gallery Embed Shoppable Galleries on your site with a quick JavaScript widget and minimal setup. Build custom Shoppable Galleries with Dash Social's API. #### Product Page Gallery Build fully custom Product Page Galleries with Dash Social's API. Embed product-linked media on PDPs using the Product Page Gallery widget. #### LikeShop Gallery Embed a LikeShop gallery or carousel on your site to showcase shoppable Instagram and TikTok posts. # Localized product feed setup guide Source: https://developer.dashsocial.com/guides/social-commerce/product-feed/localized-product-feed-setup-guide Set up localized product feeds to display region-specific prices, titles, and availability in your galleries. A localized product feed allows you to provide alternative values, such as language or currency, for product fields in your default product feed. This way, you can show localized versions of your products to customers in different countries or who speak other languages. Before importing a localized product peed, please **ensure you have a product feed imported into Dash Social that will act as the default feed**. The default feed contains all of the default versions of your products. Your default feed must also contain an column for the unique identifier (SKU, product ID, etc.) as that will be used to add the localized information to the default products. Please refer to the [Product Feed Setup Guide](https://developer.dashsocial.com/docs/product-feed-setup-guide) to set up your default feed. Please note that localized product feed does not support XML format. ## Accepted fields The following fields in the localized product feed are accepted. If your product feed uses different field names than those listed below, please provide the field mapping to your Account Representative to ensure data consistency. **Required Fields:** | Field | Type | Description | | :---- | :----- | :-------------------------------------------------------------------------------------------------- | | id | string | A unique identifier for the product. This ID should match one of the products in your default feed. | **Optional Fields:**
Field Type Description
override string The name of the locale, country code, and language code to which the product belongs. Using ISO standards for locales/country codes/language codes is recommended but not enforced. * *Note:*\* If you do not provide this field in the product feed, you must communicate with your account representative about the country or language code for which each feed is for. When using Product Page Gallery, this value can be passed to `data-override` parameter to display the localized product data. See [Product Page Gallery guide](https://developer.dashsocial.com/docs/product-page-gallery) .
url string A URL that links to the product.
title string The product name
image\_url string A URL that links to an image of the product
price string/number The price of the product. You can provide a price including the currency symbol/code (e.g., "\$80.99") or a numeric price (e.g., "80.99"). When providing a price without the currency symbol/code, it is highly recommended that the `currency_code` field also be provided.
currency\_code string A 3-letter code specifying the type of currency used for the product's price. The `currency_code` is appended to the price when displayed in the media popup only if the price is numeric (e.g., "5.99"). If the price is non-numeric (e.g., "\$5.99"), then currency\_code will not be appended. For example, if the `price` is specified as "5.99" and the `currency_code` is "CAD," the `price` will be displayed as "5.99 CAD" in the media popup. If the `price` is specified as "$5.99" with the currency symbol/code and `currency_code` is "CAD", the `price` will show as "$5.99" in the media pop-up.
availability string The current availability of the product. Acceptable values are: in stock, out of stock, preorder, available for order, discontinued.
description string The description of the product.
## Example Here is a short example of how localized product feeds could be set up. If my company and customer base are in Canada, my default feed should be in English and have prices listed in CAD. Here is an example of what that might look like: Default Feed: | id | url | title | price | currency\_code | | :- | :----------------------------------------------------------------------------------------- | :-------- | :---- | :------------- | | 1 | [https://www.dashsocial.com/en/fakeproduct/1](https://www.dashsocial.com/en/fakeproduct/1) | Product 1 | 249 | CAD | | 2 | [https://www.dashsocial.com/en/fakeproduct/2](https://www.dashsocial.com/en/fakeproduct/2) | Product 2 | 749 | CAD | | 3 | [https://www.dashsocial.com/en/fakeproduct/3](https://www.dashsocial.com/en/fakeproduct/3) | Product 3 | 1249 | CAD | | 4 | [https://www.dashsocial.com/en/fakeproduct/4](https://www.dashsocial.com/en/fakeproduct/4) | Product 4 | 2499 | CAD | French Feed: For customers in France, we want to ensure they are directed to the French website and see prices in their native currency, so we create a localized product feed that specifies the French `url`, `price`, and `currency code`. | id | url | price | currency\_code | override | | :- | :----------------------------------------------------------------------------------------------- | :---- | :------------- | :------- | | 1 | [https://www.dashsocial.com/en/fakeproduct/1/fr](https://www.dashsocial.com/en/fakeproduct/1/fr) | 171 | EUR | FR | | 2 | [https://www.dashsocial.com/en/fakeproduct/2/fr](https://www.dashsocial.com/en/fakeproduct/2/fr) | 514 | EUR | FR | | 3 | [https://www.dashsocial.com/en/fakeproduct/3/fr](https://www.dashsocial.com/en/fakeproduct/3/fr) | 858 | EUR | FR | | 4 | [https://www.dashsocial.com/en/fakeproduct/4/fr](https://www.dashsocial.com/en/fakeproduct/4/fr) | 1716 | EUR | FR | United States Feed: Since English is the primary language for customers in the United States, we do not need to provide separate product links. Still, we want to display the price in USD, so we create a localized product feed that provides `price` and `currency_code`. | id | price | currency\_code | override | | :- | :---- | :------------- | :------- | | 1 | 180 | USD | US | | 2 | 544 | USD | US | | 3 | 907 | USD | US | | 4 | 1815 | USD | US | ## Frequently asked questions **Q: We don't have a default product feed. Is it okay if we only have the localized feed?** A: In this case, we recommend selecting the most widely used product feed as the default feed and importing the other localized feeds into Dash Social. **Q: Can I have a product feed with both the default feed and localized feeds?** A: No, this is not currently supported. Please ensure you have a default product feed imported into Dash Social before importing any localized feeds. **Q: How do we determine which location the user is visiting from?** A: This is controlled by whatever localization is present on the website in which the widget code is embedded. If you have different URLs depending on the users location- the code, as an example, could be looking at the country code in the URL, then passing that to our widget. # Product feed setup guide Source: https://developer.dashsocial.com/guides/social-commerce/product-feed/product-feed-setup-guide Import and sync your product catalog with Dash Social using SFTP or URL upload. A product feed is a way to import all your product information into Dash and ensure product data stays updated with the latest details. The easiest way to integrate your product feed is by using [Facebook Product Catalog Importing](https://help.dashsocial.com/hc/en-us/articles/4415092573965-Importing-your-Facebook-Product-Catalog-to-Dash-Hudson) but if this is not an option or if you're working with a large data source (hundreds of thousands of products), there are other ways to import your products. This guide will explain everything you need to set up a product feed. ## Before starting Before starting, please ensure all your product information is up-to-date and accurate. Each product must have a unique URL and an accurate product name. ## Methods for establishing the product feed There are two ways to import your product feed without Facebook Product Catalog importing: * Upload product feed file to the designated SFTP * Upload product feed via URL * Supported URL protocols: `http`(recommended),` https`(recommended), `ftp`, `sftp` * If the file is hosted on an ftp/sftp server, please provide the username and password to access the server. * If you need to add Dash to the whitelist of IPs, please contact your Account Representative to get the list of IP addresses. If you are not using a [Facebook Product Catalog](https://help.dashsocial.com/hc/en-us/articles/4415092573965-Importing-your-Facebook-Product-Catalog-to-Dash-Hudson), please use this guide to prepare your file in the specified format with the necessary product information and **contact your Account Representative to set up the product feed.** ## Supported file types To set up the product feed, all we need is a file containing all your product information. We currently support any file with delimiter-separated values. This includes: * Tab-separated values`.tsv` * Comma-separated values `.csv` * Any text file (`.txt`) that contains delimiter-separated values * Extensible Markup Language `.xml`. Please note that localized product feed does not support `.xml` format ### Accepted fields The following fields in the product feed are accepted. If your product feed uses different field names than those listed below, please provide the field mapping to your Account Representative to ensure data consistency. **Required Fields:** | Field | Type | Description | | :---- | :----- | :------------------------------------------------------------------- | | url | string | A URL that links to the product. It must be unique for each product. | | title | string | The product name. | **Optional Fields:** Provide any number of the following fields to add the information to the given product.
Field Type Description
id string A unique identifier for the product. It can be SKU, external system product ID, etc.
image\_url string A URL that links to an image of the product. If this field is not provided, we will automatically source the product image from the URL's metadata.
price string/number The price of the product. You can provide a price including the currency symbol/code, e.g., "\$80.99," or a numeric price, e.g., "80.99." When providing a price without the currency symbol/code, it is highly recommended that the `currency_code` field also be provided.
currency\_code string A 3-letter code specifying the type of currency used for the product's price. The `currency_code` is appended to the price when displayed in the media popup only if the price is numeric (e.g., "5.99"). If the price is non-numeric (e.g., "\$5.99"), then currency\_code will not be appended. For example, if the `price` is specified as "5.99" and the `currency_code` is "CAD," the `price` will be displayed as "5.99 CAD" in the media popup. If the `price` is specified as "$5.99" with the currency symbol/code and `currency_code` is "CAD", the `price` will show as "$5.99" in the media pop-up.
availability string The current availability of the product. Acceptable values are: in stock, out of stock, preorder, available for order, discontinued.
description string The description of the product.
source\_group\_id string The product group ID, which is useful when product variants are displayed as separate products in the feed. The `source_group_id` should be used as the parent product ID for all variants, helping to establish the relationship between the main product and its variants.
## Example Here is an example of product feed: | id | url | title | price | currency\_code | | :------- | :------------------------------------------------------------------------------------------------------- | :-------------------------------- | :---- | :------------- | | CKS-1001 | [https://www.dashsocial.com/en/fakeproduct/cks-1001](https://www.dashsocial.com/en/fakeproduct/cks-1001) | Cozy Knit Sweater | 89 | CAD | | CTB-1002 | [https://www.dashsocial.com/en/fakeproduct/ctb-1002](https://www.dashsocial.com/en/fakeproduct/ctb-1002) | Classic Tote Bag | 149 | CAD | | SWE-3001 | [https://www.dashsocial.com/en/fakeproduct/swe-3001](https://www.dashsocial.com/en/fakeproduct/swe-3001) | Sleek Wireless Earbuds | 349 | CAD | | UCM-4002 | [https://www.dashsocial.com/en/fakeproduct/um-4002](https://www.dashsocial.com/en/fakeproduct/um-4002) | UltraComfort Memory Foam Mattress | 559 | CAD | ## Localized product feed A localized product feed allows you to provide alternative values, such as language or currency, for product fields in your default product feed. This way, you can show localized versions of your products to customers in different countries or who speak other languages. For more details on setting up a localized product feed, click [here](https://developer.dashsocial.com/docs/localized-product-feed-setup-guide). ## Frequently asked questions **Q: Where can I find my imported product feed(s) and their status?** A: You can find it in your Dash Social Library. Navigate to **Library > Products**, click "Import" and then "Product Feed" to view all of your established product feeds and their status. **Q: Can I modify or add my product information to the file once my product feed is established?** A: Yes. Every 24 hours, we fetch new products and update any products that have been modified or had their statuses changed. During this update process, you will see the product feed status change to "Updating." However, when modifying the existing product data, please ensure that the URL is unchanged. **Q: I understand the URL is the primary key of each product, but we need to update our domain. What should we do?** A: Please contact your Account Representative for this change so we can help you further! **Q: We have another price level for each product. Can we enter more than one price for each product?** A: Currently, only one price column is available for each product. We suggest pushing the sale price to the main price field. # Choosing between API and widget integrations Source: https://developer.dashsocial.com/guides/social-commerce/shoppable-and-product-page-galleries/choosing-between-api-and-widget-integrations Decide between the JavaScript widget and API integration methods for embedding Dash Social galleries. There are two ways to add Shoppable Galleries and Product Page Galleries to your site: * **Widget Integration** – Quick setup with a drop-in script and basic customization. * **API Integration** – Full control to design and manage the gallery with your own front-end. For LikeShop Galleries, only the Widget Integration is available. This guide helps you choose the right approach and links to detailed implementation steps. ## When to use the widget The widget is the fastest way to get a Gallery live. * No backend development required * Drop-in script with customizable layout and styles * Automatically collects views and product click tracking in Dash Social reports * Ideal for marketing teams who want control without developer support **See guide:** Embed Shoppable Galleries on your site with a quick JavaScript widget and minimal setup. Embed product-linked media on PDPs using the Product Page Gallery widget. Embed a LikeShop gallery or carousel on your site to showcase shoppable Instagram and TikTok posts. ## When to use the API The API gives you full flexibility over how the gallery looks and behaves. * Build a completely custom layout that matches your brand * Avoid third-party JavaScript to meet strict security or performance policies * Cache content server-side for faster page loads * Serve localized product info by integrating your own feeds * Power both websites and native mobile apps with the same content * Note: Tracking is not automatic—you'll need your own system to record views and clicks for reporting **See guide:** Build fully custom Product Page Galleries with Dash Social's API. Build custom Shoppable Galleries with Dash Social's API. ## Choosing the right approach * **Need a quick setup?** Use the widget. * **Need full control or a custom UI?** Use the API. * **Not sure?** Start with the widget. You can move to the API later without losing content. # Dynamic email template Source: https://developer.dashsocial.com/guides/social-commerce/shoppable-and-product-page-galleries/dynamic-email-template Dynamically pull latest media from Dash Social Boards and LikeShop into email templates. ## Overview Use static links to dynamically pull the latest media from your Dash Social Boards or LikeShop into email templates. This allows your emails to automatically display fresh content without manual updates. You can embed images or redirect links that always point to the most recent posts in a gallery. ## Link types ### Board Gallery Image Fetch the latest image from a Board gallery. ```text theme={null} https://likeshop.me/board/{board_id}/newest/{size}/{order_id}.jpeg ``` * **`board_id`**: Board gallery ID * **`order_id`**: Position in reverse chronological order (`1` = newest) * **`size`**: `thumbs` (400x400), `640` (640x640), `items` (full-size) *** ### Board Gallery Redirect URL Fetch the redirect link for a Board image. Clicking opens the product page or Instagram post. ```text theme={null} https://likeshop.me/board/{board_id}/url/newest/{order_id} ``` To choose a specific product link when multiple are tagged: ```text theme={null} https://likeshop.me/board/{board_id}/url/newest/{order_id}/{link_id} ``` *** ### LikeShop Gallery Image Fetch the latest image from a LikeShop gallery. ```text theme={null} https://likeshop.me/images/{instagram_handle}/newest/{size}/{order_id}.jpeg ``` * **`instagram_handle`**: Account username * **`order_id`**: Position in reverse chronological order (`1` = newest) * **`size`**: Same as above (`thumbs`, `640`, `items`) *** ### LikeShop Redirect URL Fetch the redirect link for a LikeShop image. ```text theme={null} https://likeshop.me/likeshop/{instagram_handle}/url/newest/{order_id} ``` To specify a particular product link: ```text theme={null} https://likeshop.me/likeshop/{instagram_handle}/url/newest/{order_id}/{link_id} ``` *** ## Example usage ```html theme={null}

Latest 3 Board Images

Latest 3 LikeShop Images

``` # Galleries overview and implementation Source: https://developer.dashsocial.com/guides/social-commerce/shoppable-and-product-page-galleries/galleries-overview-and-implementation Compare Shoppable Gallery and Product Page Gallery types and choose the right implementation for your use case. Dash Social provides 2 gallery options for showcasing product-linked media on your website: **Shoppable Galleries** and **Product Page Galleries**. ## Shoppable Gallery A curated gallery for home, collection, or campaign pages where you choose and control the media. Perfect for showcasing your best content with full editorial control. **Use Cases:** * Showcasing top-performing UGC * Featuring media across multiple products * Maintaining full control over layout, style, and display ## Product Page Gallery A product specific gallery shown on PDPs. It automatically displays all media tagged to that product and scales across your product catalog with a single integration. **Use Cases:** * Displaying product-specific content on PDPs * Automatically updating and scaling galleries across the catalog ## Comparison | Feature | Shoppable Gallery | Product Page Gallery | | ------------------------ | ---------------------------------------- | ------------------------------------------- | | **Use Case** | Curated content across multiple products | Auto-generated content for a single product | | **Placement** | Homepage, category pages, campaign pages | Product detail pages (PDPs) | | **Content Control** | Custom - you pick each media item. | Automated - based on product tags | | **Setup** | Create and embed each gallery | One-time PDP template integration | | **Widget and API** | ✅ | ✅ | | **Localization Support** | ✅ | ✅ | # LikeShop widget setup Source: https://developer.dashsocial.com/guides/social-commerce/shoppable-and-product-page-galleries/likeshop-gallery/likeshop-widget-setup Embed a shoppable LikeShop gallery or carousel on your site to link Instagram and TikTok content to products. ## Overview Use the LikeShop widget to embed a clickable gallery or carousel of posts from your LikeShop directly on your site. Posts are displayed with the most recent first, and additional content loads as users scroll. * Single-product posts open the product page in a new tab. * Multi-product posts open a pop-up with product anchors overlaid on the image. For inspiration: * [Perelel Health](https://likeshop.me/perelelhealth) * [Birdies](https://likeshop.me/birdies) * [Barefaced](https://likeshop.me/barefaced) * [Kevin Murphy](https://likeshop.me/kevin.murphy) ## Embed the widget ### Gallery layout Paste this inside the element where you want the gallery to appear. Replace `` in the examples below with your value. Keep it inside double quotes. ```javascript theme={null} ``` ### Carousel layout Use this script to create a scrolling carousel: ```javascript theme={null} ``` ## Widget parameters These parameters control the behavior and appearance of the LikeShop widget. If you are interested in more advanced styling and customization, refer to the Widget Customization Guide: Customize Dash Social widgets with CSS for fonts, colors, and layout tweaks. | Parameter | Required | Format | Description | | :----------------------------- | :------- | :--------------- | :---------------------------------------------------------------------------- | | `data-id` | Yes | Gallery/Carousel | Replace `` with your Brand ID. Wrap in double quotes. | | `data-id-type` | Yes | Gallery/Carousel | Type of ID used in `data-id`. Use `"brand_id"`. | | `data-row-size` | No | Gallery/Carousel | Images per row. Default is 3. | | `data-gap-size` | No | Gallery/Carousel | Spacing between images in pixels. Default is 2. | | `data-mobile-row-size` | No | Gallery/Carousel | Images per row on mobile. Defaults to `data-row-size`. | | `data-mobile-gap-size` | No | Gallery/Carousel | Spacing between images on mobile. Defaults to `data-gap-size`. | | `data-call-to-action` | No | Gallery/Carousel | Add a hover overlay message (e.g. `"shop_now"`, `"learn_more"`). | | `data-lazy` | No | Gallery/Carousel | Load images only when they are in view. | | `data-disable-product-new-tab` | No | Gallery/Carousel | Default is `"false"`. If set to `"true"`, product links open in the same tab. | | `data-carousel-dots` | No | Carousel | Show or hide navigation dots below the carousel. Default is `true`. | | `data-autoplay` | No | Carousel | Enable automatic scrolling. Default is `"false"`. | | `data-infinite` | No | Carousel | Enable infinite looping. Default is `"false"`. | | `data-show-price` | No | Gallery/Carousel | Show product prices in the pop-up if available in your product feed. | ## Content Security Policy If your site uses a Content Security Policy (CSP), you'll need to allow the domains and MIME types used by the LikeShop Widget. This ensures scripts, images, and network calls load correctly. ### Why this matters * Ensures the widget script can load safely. * Allows image and video assets from approved Dash Social domains. * Prevents CSP errors that block network calls or media loading. ### Required CSP directives ```html theme={null} script-src https://cdn.dashsocial.com; connect-src https://likeshop.me; img-src 'self' data: https://cdn.dashsocial.com https://likeshop.me https://dashsocial-static.s3.amazonaws.com https://d1cka1o15bmsqv.cloudfront.net https://dashsocial.com https://www.dashsocial.com ``` ### Approved domains and MIME types * **[https://cdn.dashsocial.com](https://cdn.dashsocial.com)** * `application/javascript` * `image/jpeg` * `video/mp4` * **[https://likeshop.me](https://likeshop.me)** * `text/html` * `image/png` * `image/gif` * `application/json` * **data:** * `application/font-woff` * `image/png` * **[https://dashsocial-static.s3.amazonaws.com](https://dashsocial-static.s3.amazonaws.com)** * `image/jpeg` * `video/mp4` * **[https://d1cka1o15bmsqv.cloudfront.net](https://d1cka1o15bmsqv.cloudfront.net)** * `image/jpeg` * `video/mp4` * **[https://dashsocial.com](https://dashsocial.com)** * `text/html` * **[https://www.dashsocial.com](https://www.dashsocial.com)** * `text/plain` # Product Page Galleries: API integration guide Source: https://developer.dashsocial.com/guides/social-commerce/shoppable-and-product-page-galleries/product-page-gallery/product-page-galleries-api-integration-guide Build fully custom Product Page Galleries using the Dash Social API for product detail pages. ## Overview Use Dash Social's API to build fully custom Product Page Galleries that match your brand's layout and infrastructure. The API gives you complete design control, avoids third-party JavaScript, and supports server-side caching for fast page loads. You can integrate it into any web or mobile stack. For a quick, prebuilt option with minimal setup, see the Product Page Gallery Widget → Embed product-linked media on PDPs using the Product Page Gallery widget. ## Before starting To implement a product gallery, make sure: * Your product feed is set up and synced in the Dash Library. [Set up your product feed](https://developer.dashsocial.com/guides/social-commerce/product-feed/product-feed-setup-guide). * Your media is linked to products in the Library. [Learn how](https://help.dashsocial.com/hc/en-us/articles/4426716747789-Implementing-Product-Page-Galleries#h_01H9V4M3DA2TCEVE7MQ00DEMR1). ### Access requirements * No API key or authentication required * Rate limited per IP address ## Key concepts * **`product_source_id`**: Unique product identifier (SKU) from your feed * **`product_source_group_id`**: Shared ID used to group product variants into a single gallery * **`hide_in_widget`**: Flag to exclude media from rendering. Filter these out before displaying the gallery ## Implementation ### Query media by product ID #### Step 1: Find the product ID/SKU This should match the product's ID in your e-commerce system and in your product feed. #### Step 2: Make the API call This query returns all media tagged to the product with `product_source_id = APPLE-001`, along with product metadata and localization fields: ```http theme={null} GET https://library-backend.dashsocial.com/public/brands/{brand_id}/products/media?product_source_id=APPLE-001 ``` For full parameter and response details, see the [API reference](/api-reference/library/product/retrieve-product-media). ### Querying media for multiple products #### When to use You have product variants like T-shirt Red, Yellow, and Blue but want to group them into a single gallery on your PDP. #### Step 1: Add group ID to your feed To group related products, add a group ID column in your product feed. Each variant should share the same group ID (e.g., `TSHIRT`). | SKU | Group ID | | ------------- | -------- | | TSHIRT-RED | TSHIRT | | TSHIRT-BLUE | TSHIRT | | TSHIRT-YELLOW | TSHIRT | This setup is required. The API won't return grouped media unless the group ID is present and consistent across variants in the feed. Populate this column with the parent product's ID (e.g., `TSHIRT`) for each variant row. #### Step 2: Query with product\_source\_group\_id ```http theme={null} GET https://library-backend.dashsocial.com/public/brands/{brand_id}/products/media?product_source_group_id=TSHIRT ``` This fetches all media linked to product variants sharing the group ID `TSHIRT`. ### API behavior tips #### Hidden media * If a media item has `hide_in_widget: 1`, it has been marked as hidden from the product page gallery in the Dash UI. * These media are still included in API responses. * Filter them out before rendering the gallery. #### TikTok media is returned as images * Due to a technical limitation, TikTok media always appears with `"type": "IMAGE"` in API responses. * Use the `tiktok.embed_url` field to render the playable video directly in your gallery. ### Sample response ```json theme={null} [ { "brand_id": "", "duration": null, "hide_in_widget": 0, "image_sizes": { "medium_square": { "height": 640, "url": "https://images.dashsocial.com/...", "width": 640 }, "original": { "height": 678, "size": 486884, "url": "https://cdn.dashsocial.com/...", "width": 742 }, "original_converted": { "height": 678, "size": 54095, "url": "https://cdn.dashsocial.com/...", "width": 742 }, "small": { "height": 400, "url": "https://images.dashsocial.com/...", "width": 437 }, "small_square": { "height": 400, "url": "https://images.dashsocial.com/...", "width": 400 } }, "media_group": "365399013", "media_id": 368799697, "media_type": "IMAGE", "original_height": "678", "original_width": "742", "predictions": { "eng": 0.33188 }, "products": [ { "bounding_box": null, "deleted": 0, "description": "Fresh seasonal apple.", "hide_in_widget": 0, "id": 6124998, "image_url": "https://cdn.dashsocial.com/products/original_images/...", "product": { "archived": false, "availability": null, "brand_id": "", "currency_code": null, "description": "Fresh seasonal apple.", "id": 61448488, "image_url": "https://cdn.dashsocial.com/products/original_images/...", "is_disabled": 0, "price": null, "product_overrides": [ { "currency_code": null, "id": 2830105, "override": "FR", "price": null, "source_id": "APPLE-001", "title": "Pomme", "url": null } ], "source_group_id": null, "source_id": "APPLE-001", "status": "READY_PROC", "title": "Apple", "url": "https://example.com/products/apple" }, "product_groups": [ { "country_code": null, "description": "Fresh seasonal apple.", "image_url": "https://cdn.dashsocial.com/products/original_images/...", "source_id": "APPLE-001", "title": "Apple", "url": "https://example.com/products/apple" } ], "product_id": 61448488, "source_id": "APPLE-001", "title": "Apple", "url": "https://example.com/products/apple", "x": 0.532609, "y": 0.47619 } ], "source_data": null, "type": "UPLOADED", "urls": { "640": "https://images.dashsocial.com/...", "full": "https://cdn.dashsocial.com/...", "original": "https://cdn.dashsocial.com/...", "ratio": "https://images.dashsocial.com/...", "thumbs": "https://images.dashsocial.com/..." }, "video_sizes": {} }, { "brand_id": "", "duration": null, "hide_in_widget": 1, "image_sizes": { "medium_square": { "height": 640, "url": "https://images.dashsocial.com/...", "width": 640 }, "original": { "height": 1080, "size": 312044, "url": "https://cdn.dashsocial.com/...", "width": 1080 } }, "media_group": "412057891", "media_id": 412057892, "media_type": "IMAGE", "original_height": "1080", "original_width": "1080", "predictions": { "eng": 0.61204 }, "products": [ { "bounding_box": null, "deleted": 0, "description": "Fresh seasonal apple.", "hide_in_widget": 0, "id": 6124999, "image_url": "https://cdn.dashsocial.com/products/original_images/...", "product": { "archived": false, "availability": null, "brand_id": "", "currency_code": null, "description": "Fresh seasonal apple.", "id": 61448488, "image_url": "https://cdn.dashsocial.com/products/original_images/...", "is_disabled": 0, "price": null, "product_overrides": [], "source_group_id": null, "source_id": "APPLE-001", "status": "READY_PROC", "title": "Apple", "url": "https://example.com/products/apple" }, "product_groups": [ { "country_code": null, "description": "Fresh seasonal apple.", "image_url": "https://cdn.dashsocial.com/products/original_images/...", "source_id": "APPLE-001", "title": "Apple", "url": "https://example.com/products/apple" } ], "product_id": 61448488, "source_id": "APPLE-001", "title": "Apple", "url": "https://example.com/products/apple", "x": 0.45, "y": 0.52 } ], "source_data": { "caption": "Loving the new harvest season! #fresh #organic", "hashtags": ["fresh", "organic"], "id": "17854321098765432", "image_url": "https://images.dashsocial.com/...", "instagram_media_type": "IMAGE", "instagram_user": { "id": "987654321", "username": "example_user" }, "like_count": 284, "timestamp": "2025-09-12T14:22:00+0000", "type": "INSTAGRAM_UGC", "url": "https://www.instagram.com/p/..." }, "type": "INSTAGRAM_UGC", "urls": { "640": "https://images.dashsocial.com/...", "full": "https://cdn.dashsocial.com/...", "original": "https://cdn.dashsocial.com/...", "ratio": "https://images.dashsocial.com/...", "thumbs": "https://images.dashsocial.com/..." }, "video_sizes": {} } ] ``` ## Server-side caching To improve load speed and reduce API calls, cache Product Page Gallery data on your server instead of requesting it on every page load. ### Why cache API responses? * **Faster PDP load times:** Serve gallery content instantly from your backend. * **Lower API usage:** Avoid duplicate requests and hitting rate limits. * **Consistent experience:** Cached content ensures pages load smoothly without waiting on a live API call. ### How long should you cache? * The ideal cache duration depends on how frequently you update product media or information. * If product media rarely changes, you can cache for **12–24 hours** or longer. * If updates are frequent, use a shorter TTL (e.g., **1–2 hours**) to keep galleries fresh. **Tip:** Choose a cache duration that matches your update frequency. This balances performance with content accuracy. # Product Page Gallery widget setup Source: https://developer.dashsocial.com/guides/social-commerce/shoppable-and-product-page-galleries/product-page-gallery/product-page-gallery-widget-setup Embed product-linked media on product detail pages using the Product Page Gallery widget. ## Overview The Product Page Gallery Widget displays product-linked media in a carousel on your product pages. It matches the product's URL on the page with the URL in your Dash Social library to pull relevant media. Clicking on a post opens a popup with product details and tagged products. You can disable the popup using the `data-links-disabled` parameter. ## Before you start * Get your **brand ID** . * Make sure your products in the library have URLs that match your product page URLs. ## Embed the widget To add the Product Page Gallery Widget, place the script inside any product page template. For e-commerce platforms with a shared PDP template, you only need to add the script once. Replace `` with your Dash Social brand ID. Keep the value wrapped in double quotes. ```javascript theme={null} ``` ### Displaying localized products To display localized product data, use the data-override parameter. This value must match the override in your localized product feed. When using localized feeds, you must also include the data-product-id parameter, matching the product's unique identifier (e.g., SKU) from the feed. ```javascript theme={null} ``` ## Widget parameters These parameters control the behavior and appearance of the Product Page Gallery widget. If you are interested in more advanced styling and customization, refer to the Widget Customization Guide: Customize Dash Social widgets with CSS for fonts, colors, and layout tweaks. | Parameter | Required | Description | | ------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `data-id` | Yes | Your brand ID. Wrap it in double quotes. | | `data-id-type` | Yes | Specifies the type of ID used. Must be `"brand_id"`. | | `data-row-size` | No | Number of images per row. Defaults to `3` if not specified. | | `data-gap-size` | No | Space between images in pixels. Default is `2`. | | `data-mobile-row-size` | No | Number of images per row on mobile. Defaults to `data-row-size`. | | `data-mobile-gap-size` | No | Space between images on mobile. Defaults to `data-gap-size`. | | `data-call-to-action` | No | Hover label text. Default is `"learn_more"`. Examples: `"shop_now"`, `"book_now"`. | | `data-lazy` | No | Lazy-loads images when they enter view. | | `data-links-disabled` | No | Disables the product detail popup when media is clicked. | | `data-hide-popup-footer` | No | Hides the Dash Social logo in the popup footer. | | `data-high-res` | No | Show high-resolution images (`1`, default) or low-resolution (`0`). | | `data-media-format` | No | Controls image resolution and format. Options: `optimized` (recommended for crisp images with smaller file size), `original` (raw source files, can be 10MB+), `ratio` (smaller aspect-preserving images for page speed). Overrides `data-high-res`. | | `data-scroll-disabled` | No | Hides the carousel scroll buttons. | | `data-autoplay` | No | Automatically scroll the carousel. Default is `false`. | | `data-autoplay-speed` | No | Time in milliseconds between automatic carousel scrolls. Only applies when `data-autoplay` is `true`. Default is `5000`. | | `data-infinite` | No | Loop carousel back to start. Default is `false`. | | `data-carousel-dots` | No | Show carousel navigation dots. Default is `false`. Set to `true` to display them. | | `data-disable-product-new-tab` | No | Default is `"false"`. When set to `"true"`, clicking a product link opens in the same tab instead of a new tab. | | `data-show-price` | No | Show product price from the product feed in the popup. Default is `false`. | | `data-override` | No | Required to display localized product feed data. Must match the `override` value on the feed. | | `data-product-id` | No | Required for localized feeds. Matches the product's SKU or unique identifier. | | `data-use-product-group` | No | **Requires `data-product-id`.** When `true`, matches products by group ID from the product feed instead of URL. If no group ID exists, no media is returned. | | `data-minimum-media` | No | Minimum number of media items required for the gallery to display. | | `data-media-types` | No | Filter media by source. Accepts comma-separated values like `"INSTAGRAM_UGC,TIKTOK_UGC"`. Supported values: `TIKTOK_OWNED`, `INSTAGRAM_OWNED`, `INSTAGRAM_STORY`, `FACEBOOK_OWNED`, `PINTEREST_OWNED`, `TWITTER_OWNED`, `THREADS_OWNED`, `LINKEDIN_OWNED`, `TIKTOK_UGC`, `INSTAGRAM_UGC`, `INSTAGRAM_STORY_UGC`, `UPLOADED`. | ## Content Security Policy If your site uses a Content Security Policy (CSP), you'll need to allow the domains and MIME types used by the Product Page Gallery Widget. This ensures scripts, images, and network calls load correctly. ### Why this matters * Ensures the widget script can load safely. * Allows image and video assets from approved Dash Social domains. * Prevents CSP errors that block network calls or media loading. ### Required CSP directives ```html theme={null} script-src https://cdn.dashsocial.com; connect-src https://likeshop.me; img-src 'self' data: https://cdn.dashsocial.com https://likeshop.me https://dashsocial-static.s3.amazonaws.com https://d1cka1o15bmsqv.cloudfront.net https://dashsocial.com https://www.dashsocial.com ``` ### Approved domains and MIME types * [**https://cdn.dashsocial.com**](https://cdn.dashsocial.com) * `application/javascript` * `image/jpeg` * `video/mp4` * [**https://likeshop.me**](https://likeshop.me) * `text/html` * `image/png` * `image/gif` * `application/json` * **data:** * `application/font-woff` * `image/png` * [**https://dashsocial-static.s3.amazonaws.com**](https://dashsocial-static.s3.amazonaws.com) * `image/jpeg` * `video/mp4` * [**https://d1cka1o15bmsqv.cloudfront.net**](https://d1cka1o15bmsqv.cloudfront.net) * `image/jpeg` * `video/mp4` * [**https://dashsocial.com**](https://dashsocial.com) * `text/html` * [**https://www.dashsocial.com**](https://www.dashsocial.com) * `text/plain` # Build shoppable galleries with the API Source: https://developer.dashsocial.com/guides/social-commerce/shoppable-and-product-page-galleries/shoppable-gallery/build-shoppable-galleries-with-the-api Build fully custom shoppable galleries using the Dash Social API for complete design control. ## Overview Use Dash Social's API to build fully custom Shoppable Galleries that match your brand's layout and infrastructure. The API gives you complete design control, avoids third-party JavaScript, and supports server-side rendering with localized product data. For a fast, prebuilt option with minimal setup, see the Shoppable Gallery Widget → Embed Shoppable Galleries on your site with a quick JavaScript widget and minimal setup. ## Before you start You'll need: * **Brand ID**: Visible in your developer settings or next to your brand name in the platform * **Gallery ID**: Retrieved from the URL in Dash Social (see Step 2) * Your product feed is set up and synced in the Dash Library. [Set up your product feed](https://developer.dashsocial.com/guides/social-commerce/product-feed/product-feed-setup-guide). ### Access requirements * No API key or authentication required * Rate limited per IP address ## Implementation ### Step 1: Create a gallery in Dash Social If you haven't already created a gallery: 1. Go to the **Library** and click **Add Gallery** 2. Add UGC or owned media by clicking **Add Media** 3. Tag each media item with products by selecting **Link** Already have a gallery? Skip this step and jump to Step 2. ### Step 2: Retrieve the gallery ID Once the gallery is created, get your `gallery_id` from the URL. **Example URL:** ```text theme={null} https://app.dashsocial.com/{brand_name}/library/galleries?sort=CREATED&sort_order=DESC&tags_filter_type=OR&graph_start_date=2025-05-29&graph_end_date=2025-06-04&graph_scale=DAILY&graph_reporting_period_mode=LAST_7_DAYS&d=boardDetail%7CboardId%3A5448990%26galleryType%3ALIBRARY%26isCompetitors%3Afalse ``` * `%3A` is a URL-encoded colon `(:)` * The **Gallery ID** is the number directly after `boardId:` In this case, it's `5448990` ### Step 3: Retrieve gallery content Use the following endpoint to get the media associated with a gallery: ```http theme={null} GET https://library-backend.dashsocial.com/public/brands/{brand_id}/galleries/{gallery_id}/media?sort=ORDER ``` This endpoint requires no API key. You can call it directly from your frontend without exposing credentials. It works from the backend too. * `sort`: Sorts media by field. Prefix with `-` for descending order. Common values: * `ORDER`: Returns media in the same order as the Dash UI * `PUBLISHED_AT`: Sorts by publish date, newest first * `PERFORMANCE`: Sorts by engagement performance For full parameter and response details, see the [API reference](/api-reference/library/publicgallery/get-publicbrands-galleries-media). Sample response: ```json theme={null} { "data": [ { "brand_media_type": "LINKEDIN_OWNED", "id": 72896870, "media": { "duration": null, "id": 652015248, "image_sizes": { "medium_square": { "height": 640, "url": "https://images.dashsocial.com/...", "width": 640 }, "original": { "height": 366, "url": "https://images.dashsocial.com/...", "width": 550 } }, "source": "LINKEDIN", "type": "IMAGE", "urls": { "full": "https://images.dashsocial.com/...", "thumbs": "https://images.dashsocial.com/..." }, "video_sizes": {} }, "order": 6.0, "products": [] }, { "brand_media_type": "LINKEDIN_OWNED", "id": 72896866, "media": { "duration": 11.266667, "id": 656722487, "image_sizes": { "medium_square": { "height": 640, "url": "https://images.dashsocial.com/...", "width": 640 }, "original": { "height": 1280, "url": "https://cdn.dashsocial.com/...", "width": 720 } }, "source": "LINKEDIN", "type": "VIDEO", "urls": { "full": "https://cdn.dashsocial.com/...", "thumbs": "https://images.dashsocial.com/..." }, "video_sizes": { "original": { "height": 1280, "size": 2122842, "url": "https://cdn.dashsocial.com/...", "width": 720 } } }, "order": 10.0, "products": [ { "id": 9633502, "image_url": null, "source_id": null, "title": "Product Title", "url": "https://example.com/product", "x": 0.433333, "y": 0.4625 } ] } ], "paging": { "count": 12, "next": null, "previous": null } } ``` **Pro tip:** Cache gallery data in your backend to reduce load times and API usage. If speed is a high priority feature for you, we recommend caching the results to avoid calling the API every time users load your website. ### Filter archived products Each product in the response includes an `archived` field. Use it to decide whether to hide or display archived products differently in your gallery. ```json theme={null} { "archived": false, "id": 9633502, "title": "Product Title" } ``` * `archived: true`: the product is archived * `archived: false`: the product is active ### Step 4: Render the gallery on your website Now that you have the media data and linked product data, render the gallery in any format that fits your site design: carousel, grid, list, or any other layout. *** ## Optional: Display UGC creator info and caption By default, the gallery API returns a summarized response without post-level metadata. If you want to show creator handles, captions, or engagement details in your gallery UI, you need to use the private authenticated endpoint with `summary=0`. This requires an API key. The public endpoint does not return `source_data`. Generate an API key and make your first authenticated request. ```http theme={null} GET https://library-backend.dashsocial.com/brands/{brand_id}/galleries/{gallery_id}/media?summary=0 ``` When `summary=0` is set, each media item includes a `source_data` object with post-level and user-level metadata. For Instagram UGC, use `media.source_data.instagram_user.handle` to display the creator's handle. Sample response: ```json theme={null} { "data": [ { "brand_media_type": "INSTAGRAM_UGC", "id": 54378431, "media": { "duration": null, "id": 460069447, "image_sizes": { "medium_square": { "height": 640, "url": "https://images.dashsocial.com/...", "width": 640 }, "original": { "height": 1800, "url": "https://cdn.dashsocial.com/...", "width": 1440 } }, "source": "INSTAGRAM", "source_data": { "caption": "Loving the new summer collection! #summer #ootd", "hashtags": ["summer", "ootd"], "id": "17927322830848120", "image_url": "https://cdn.dashsocial.com/...", "instagram_media_type": "FEED", "instagram_user": { "followers": 12400, "handle": "example_creator", "instagram_id": 64685177677, "is_business": 0 }, "like_count": 184, "timestamp": "2025-04-08T13:19:48+0000", "type": "image", "url": "https://www.instagram.com/p/..." }, "type": "IMAGE", "urls": { "full": "https://cdn.dashsocial.com/...", "thumbs": "https://images.dashsocial.com/..." }, "video_sizes": {} }, "order": 4.0, "products": [ { "id": 9633502, "image_url": "https://cdn.dashsocial.com/products/original_images/...", "source_id": "SKU-001", "title": "Summer Dress", "url": "https://example.com/products/summer-dress", "x": 0.453125, "y": 0.4625 } ] } ], "paging": { "count": 4, "next": null, "previous": null } } ``` *** ## Optional: Localize your gallery content If you serve international audiences, you can request localized product data for a specific region by adding the `include_product_overrides` parameter to your API call. This lets you: * Show translated product titles * Display region-specific pricing and currency * Link to localized product pages ### Prerequisites Before localizing your Shoppable Gallery, make sure you: * **Set up a localized product feed** in Dash Social. Follow the [Localized Product Feed Setup Guide](https://developer.dashsocial.com/guides/social-commerce/product-feed/localized-product-feed-setup-guide). * **Note your override identifier** (e.g., `DK`, `FR`). The value passed to `include_product_overrides` must match the override name configured in your Dash Social library. ### Implementation Add `include_product_overrides` to your request with the locale identifier: ```http theme={null} GET https://library-backend.dashsocial.com/public/brands/{brand_id}/galleries/{gallery_id}/media?include_product_overrides={locale} ``` For example, to request Danish product data: ```http theme={null} GET https://library-backend.dashsocial.com/public/brands/144/galleries/6925134/media?include_product_overrides=DK ``` If a product has a matching override, it is returned in the `product_overrides` array. If no match exists, the media item is still returned but `product_overrides` will be `null`. Render the localized values from `product_overrides`: * `title` * `price` and `currency_code` * `url` Fall back to the default product fields if `product_overrides` is `null`. Sample response: ```json theme={null} { "data": [ { "brand_media_type": "PINTEREST_OWNED", "id": 73746344, "media": { "duration": null, "id": 323843713, "image_sizes": { "medium_square": { "height": 640, "url": "https://images.dashhudson.com/...", "width": 640 }, "original": { "height": 900, "url": "https://images.dashhudson.com/...", "width": 1200 } }, "source": "PINTEREST", "type": "IMAGE", "urls": { "full": "https://images.dashhudson.com/...", "thumbs": "https://images.dashhudson.com/..." }, "video_sizes": {} }, "order": 0.0, "products": [ { "id": 9729122, "image_url": "https://cdn.dashhudson.com/products/original_images/...", "product_overrides": [ { "currency_code": "DKK", "id": 1118, "override": "DK", "price": "DKK 299.00", "source_id": "SKU-001", "title": "Høj hæl sandal", "url": "https://example.com/dk/products/sandal-001" } ], "source_id": "SKU-001", "title": "High Heel Sandal", "url": "https://example.com/products/sandal-001", "x": 0.728261, "y": 0.507246 }, { "id": 9729123, "image_url": null, "product_overrides": [ { "currency_code": "DKK", "id": 1119, "override": "DK", "price": "DKK 659.00", "source_id": "SKU-002", "title": "Ankelstøvle med spænde", "url": "https://example.com/dk/products/ankle-boot-002" } ], "source_id": "SKU-002", "title": "Ankle Boot", "url": "https://example.com/products/ankle-boot-002", "x": 0.396739, "y": 0.481884 } ], "updated_at": "2026-05-25T17:07:00+00:00" } ], "paging": { "count": 13, "next": null, "previous": null } } ``` ## Server-side caching Shoppable Gallery content typically updates less frequently than product pages, making it ideal for caching on your server to reduce API calls and speed up page loads. ### Why cache API responses? * **Faster gallery rendering:** Serve content instantly without waiting for a live API call. * **Lower API usage:** Minimize repeated requests and stay within rate limits. * **Stable experience:** Cached data ensures the gallery loads smoothly even during heavy traffic. ### Recommended cache duration * Since Shoppable Galleries update less often, you can safely use a longer TTL (e.g., **24–48 hours**). * If your gallery is updated regularly with new UGC or campaigns, use a shorter TTL (e.g., **6–12 hours**). **Tip:** Match the cache duration to how often you update your gallery content. Longer TTLs work best for static or seasonal galleries, while active campaigns benefit from shorter intervals. # Shoppable gallery widget setup Source: https://developer.dashsocial.com/guides/social-commerce/shoppable-and-product-page-galleries/shoppable-gallery/shoppable-gallery-widget-setup Embed a shoppable gallery on your site with a JavaScript widget and minimal setup. ## Overview Use the Shoppable Gallery widget to embed your gallery on any page of your site without coding. It pulls in the media you've added to the gallery and displays it in either a grid or carousel layout. ## Before you start Make sure you have the following: * **Code access** to the page where you want to embed the script * **Gallery ID**: Retrieved from the URL in the Dash Social platform. * Once your gallery is created in Dash Social, you can find its ID in the URL. Example URL: * ```text theme={null} https://app.dashsocial.com/{brand_name}/library/galleries?sort=CREATED&sort_order=DESC&tags_filter_type=OR&graph_start_date=2025-05-29&graph_end_date=2025-06-04&graph_scale=DAILY&graph_reporting_period_mode=LAST_7_DAYS&d=boardDetail%7CboardId%3A5448990%26galleryType%3ALIBRARY%26isCompetitors%3Afalse ``` * `%3A` is a URL-encoded colon (`:`) * Look for the number after `boardId:` * In this case, the **Gallery ID** is `5448990` ## Embed the widget Choose between **Gallery Layout** and **Carousel Layout** based on your design preferences. * Use **Gallery Layout** to show rows of media * Use **Carousel Layout** for a scrollable horizontal strip ### Gallery layout Place the following code inside an element on the page you would like it to appear on, replace `` in line 5 with your Gallery ID: ```javascript theme={null} ``` ### Carousel layout Place the following code inside an element on the page you would like it to appear on, replace `` in line 5 with your Gallery ID: ```javascript theme={null} ``` ## Widget parameters These parameters control the behavior and appearance of the Shoppable Gallery widget. If you are interested in more advanced styling and customization, refer to the Widget Customization Guide: Customize Dash Social widgets with CSS for fonts, colors, and layout tweaks. | Parameter | Required | Applies To | Description | | :----------------------------- | :------: | :----------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `data-gallery-id` | Yes | Gallery / Carousel | Gallery ID to load. | | `data-row-size` | No | Gallery / Carousel | Number of images per row. Default: `3`. | | `data-row-limit` | No | Gallery | Limits the number of rows displayed. No limit by default. | | `data-gap-size` | No | Gallery / Carousel | Spacing between images (pixels). Default: `2`. | | `data-mobile-row-size` | No | Gallery / Carousel | Images per row on mobile. Defaults to `data-row-size`. | | `data-mobile-gap-size` | No | Gallery / Carousel | Spacing between images on mobile. Defaults to `data-gap-size`. | | `data-call-to-action` | No | Gallery / Carousel | Adds a hover CTA. Options: `learn_more`, `shop_now`, `book_now`. | | `data-lazy` | No | Gallery / Carousel | Loads images with `loading="lazy"` for performance. | | `data-links-disabled` | No | Gallery / Carousel | Disables the media popup when clicking an image. | | `data-hide-popup-footer` | No | Gallery / Carousel | Removes the Dash Social footer from the popup. | | `data-high-res` | No | Gallery / Carousel | Controls image resolution. `1` = high-res (default), `0` = low-res. | | `data-media-format` | No | Gallery / Carousel | Controls image resolution and format. Options: `optimized` (recommended for crisp images with smaller file size), `original` (raw source files, can be 10MB+), `ratio` (smaller aspect-preserving images for page speed). Overrides `data-high-res`. | | `data-disable-product-new-tab` | No | Gallery / Carousel | Default `false`. Set `true` to open product links in the same tab. | | `data-scroll-disabled` | No | Carousel | Hides scroll buttons. | | `data-autoplay` | No | Carousel | Auto-scrolls the carousel. `true` / `false` (default). | | `data-infinite` | No | Carousel | Wraps carousel to start/end. `true` / `false` (default). | | `data-carousel-dots` | No | Carousel | Shows navigation dots. `true` / `false` (default). | | `data-show-price` | No | Gallery / Carousel | Shows tagged product prices in the popup. Requires `price` + `currency_code` in your product feed. | | `data-override` | No | Gallery / Carousel | Required for localized product feeds. Matches the `override` value in your feed. | ## Content Security Policy If your site uses a Content Security Policy (CSP), you'll need to allow the domains and MIME types used by the Shoppable Gallery Widget. This ensures scripts, images, and network calls load correctly. ### Why this matters * Ensures the widget script can load safely. * Allows image and video assets from approved Dash Social domains. * Prevents CSP errors that block network calls or media loading. ### Required CSP directives ```html theme={null} script-src https://cdn.dashsocial.com; connect-src https://likeshop.me; img-src 'self' data: https://cdn.dashsocial.com https://likeshop.me https://dashsocial-static.s3.amazonaws.com https://d1cka1o15bmsqv.cloudfront.net https://dashsocial.com https://www.dashsocial.com ``` ### Approved domains and MIME types * **[https://cdn.dashsocial.com](https://cdn.dashsocial.com)** * `application/javascript` * `image/jpeg` * `video/mp4` * **[https://likeshop.me](https://likeshop.me)** * `text/html` * `image/png` * `image/gif` * `application/json` * **data:** * `application/font-woff` * `image/png` * **[https://dashsocial-static.s3.amazonaws.com](https://dashsocial-static.s3.amazonaws.com)** * `image/jpeg` * `video/mp4` * **[https://d1cka1o15bmsqv.cloudfront.net](https://d1cka1o15bmsqv.cloudfront.net)** * `image/jpeg` * `video/mp4` * **[https://dashsocial.com](https://dashsocial.com)** * `text/html` * **[https://www.dashsocial.com](https://www.dashsocial.com)** * `text/plain` # Widget customization Source: https://developer.dashsocial.com/guides/social-commerce/shoppable-and-product-page-galleries/widget-customization Customize the appearance of Shoppable Gallery, Product Page Gallery, and LikeShop widgets using CSS. This guide shows how to apply custom styles to Dash Social embeddable widgets, including **Shoppable Galleries**, **Product Page Galleries**. and **Likeshop Galleries**. Use these techniques to match widgets with your brand's style and voice. You can: * Adjust layout and aspect ratios * Customize hover effects and overlays * Modify product pop-up designs * Add dynamic headers above widgets All examples work for both carousel and grid layouts. ## Before you start * Make sure the widget script is embedded and functioning on your site. * Add custom styles inside `` tags in your CSS or HTML file. * Most changes target widget classes using CSS overrides. ## Gallery customizations ### Change aspect ratio By default, the widget crops all images into a square (1:1) format so the gallery layout stays even. To use a different aspect ratio, add `data-media-format="original"` to the script tag and update the CSS to control how images fill each cell. Add `data-media-format="original"` to your script tag: ```html theme={null} ``` Then add the following CSS to set your target ratio and ensure images fill the container: ```html theme={null} ``` * `padding-top`: Controls the aspect ratio. Values greater than 100% produce a portrait crop; values less than 100% produce a landscape crop. For example, `125%` gives a 4:5 ratio and `133.33%` gives a 2:3 ratio. * `data-media-format="original"`: Required when using a custom aspect ratio. Without it, the widget overrides your CSS and forces a square crop. Note that images with very different native ratios may still appear uneven without additional custom styling. ### Add hover behavior Enable a hover overlay with a custom call-to-action. ```javascript theme={null} ``` ### Customize overlay color Change the background color of the hover overlay. ```javascript theme={null} ``` ### Shadow on hover Add a hover effect with smooth animation. ```javascript theme={null} ``` ```javascript theme={null} ``` ### Stylized hover behaviour You can add rounded corners, a gradient background, and smooth movement to create a more dynamic hover effect. ```html theme={null} ``` **For Shoppable Gallery and LikeShop Widgets** Add these adjustments to control spacing and columns: ```html theme={null} ``` * `margin`: Controls spacing between items. Adjust as needed. * `width: (100% / 4) !important;`: Sets the grid to 3 columns. Use `100% / (columns + 1)` (e.g., `100% / 6` for 5 columns). ### Custom header above widget Many brands add a custom header above their Shoppable or Product Page Galleries. A common pattern is hiding the header if no media is available for that page. You can achieve this with a small JavaScript snippet that checks the widget's content. ```html theme={null}

#Plants

``` ## Product pop-up customizations When a user clicks on a post in a Shoppable Gallery or Product Page Gallery, a product pop-up opens. This pop-up displays: The media the user clicked on A list of all products tagged in that post Links that take the user to the product pages You can customize the appearance of this pop-up to better match your brand style using CSS. Below is a basic widget example that includes the pop-up. The following sections will show how to adjust colors, fonts, and layout. ```html theme={null}

Example

``` ### Show product price Display product prices if available in your feed. ```javascript theme={null} ``` ### Custom font You can change the font used in the pop-up by overriding the font-family CSS property. To use a custom font, import it in your \ ``` * `@import url(...)` – Loads the custom font. Replace the URL with your own font file or provider. * `font-family` – Sets the pop-up font. Replace "Roboto Mono" with your custom or built-in font. Example with \ in \: ```html theme={null} ``` This approach is useful if you're already managing fonts through external stylesheets. ### Custom background You can override the default white background of the pop-up by targeting its container elements. ```javascript theme={null} ``` * `background` – Sets a custom color for the header, footer, and main content area. * `color` – Adjust text color to ensure readability against your background. To style the header and footer differently, split the selectors and assign unique colors. ### Custom product backgrounds You can also style individual product items inside the pop-up. The example below alternates colors for even and odd items. ```html theme={null} ``` * `padding: 0 `– Removes extra space from the container so the background color fills the area. * `padding: 8px` – Adds spacing around each product item for better readability. * `:nth-child(even/odd)` – Alternates background colors for visual separation. ### Custom buttons You can replace the default close, previous, and next buttons in the pop-up with your own icons by overriding their background images. ```html theme={null} ``` * `background` – Sets the image for the button. * `background-size` – Controls the icon size inside the button. * `background-position` – Centers the icon. #### Applying to next/previous buttons You can target .ls-btn-next and .ls-btn-prev the same way to style navigation buttons: ```css theme={null} .ls-detail .ls-btn-next, .ls-detail .ls-btn-prev { background: url('/path/to/icon.png') no-repeat center; } ``` ### Reverse product layout By default, the pop-up layout places the media on the left and products on the right. You can flip this order using a simple CSS override. ```css theme={null} ``` * flex-direction: column-reverse – Stacks products above the media on mobile. * flex-direction: row-reverse – Flips positions side-by-side on desktop. You can adjust the breakpoint (850px) to match your site's responsive layout. # Upload Media To Dash Social Library Source: https://developer.dashsocial.com/guides/social-commerce/upload-media-to-dash-hudson-library Upload media directly from your CMS to your Dash Social Library # Overview This guide offers a streamlined process for uploading media to the Dash Social Library using an API. It is designed to help efficiently manage and scale the scheduling of your assets, connecting your CMS and asset management tools to Dash Social. Use this workflow as a starting point to explore new ways to scale and enhance your brand's social presence. # Key use cases * **Content Lifecycle Management:** Leverage Dash Social's suite of APIs, including Dashboards, Scheduling, and Library Media, to streamline your content creation from inception to publishing and analytics. * **Asset Automation:** Automatically upload approved assets to ensure correct and timely posting on social media. * **Vision AI for Real-Time Feedback:** During product and model photo shoots, instantly upload media for near real-time analysis of potential social media performance using our Vision AI model. * **Streamline User-Generated Content (UGC) Uploads:** Seamlessly integrate and make user-generated media from your stores and other sources accessible to your social teams. If you haven't already, make sure to go through the [Quickstart guide](/guides/get-started/quickstart) to ensure you have your `brand_id` and `API KEY`. # Get Started You can skip the first two steps if your media is already available on a public link for the upload. ## Step 1: Create an s3 upload URL Dash Social offers an s3 object URL for uploading your binary media data. You can generate an empty s3 URL by calling the endpoint and specifying the required filename and content\_type. If your asset is already hosted on a public CDN, you can skip this step. ``` POST https://library-backend.dashsocial.com/media_upload_url Body = { "filename": "filename", "content_type": "mimeType" } ``` ## Step 2: Upload media Using the s3 link you've created, remove all the query parameters by performing an operation like split('?'). Then, stream your media in binary format. Additionally, you can reuse the uploaded media URL if you choose not to use our s3 URL above. This is useful for cases where you are uploading the same media to multiple brand libraries on Dash Social. ``` PUT "https://dashsocial-static.s3-accelerate.amazonaws.com/images/uploads/1706286004.872624911672.png" Headers = { "Content-Type": "mimeType", "Cache-Control": "no-cache", "Accept": "application/json", "Connection": "keep-alive", "content-length": "content-length" } Body = { Binary media data } ``` ## Step 3: Create the media in Dash Social Library Now that you've uploaded the media, the next step is to create it in the Dash Social Library. This makes it accessible for use. See the [endpoint's reference](https://developer.dashsocial.com/api-reference/library/media/create-a-media-object) for more info. ``` POST https://library-backend.dashsocial.com/brands//media { "source": "UPLOAD", "source_id": "uuid", "type": "UPLOADED", "url": "your media url here/s3 link", "meta": "{filename: filename}", "source_created_at": "creation timestamp" } ``` You should now have your media uploaded to the Dash Social Library. ## Optional: Retrieving Media To retrieve your media, make requests to the media/v2 endpoint. For detailed information, refer to the [endpoint's reference documentation](https://developer.dashsocial.com/api-reference/library/media/retrieve-media). As a guide, here is an example of such a request: ```json theme={null} PUT https://library-backend.dashsocial.com/brands//media/v2 body = { "limit": 99, "offset": 0, "filters": { "brand_media_types": [ "UPLOADED" ], "source_created_at": { "end": "2022-01-10", "start": "2022-01-01" } } } ``` If you need help at any point please reach out to [support@dashsocial.com](mailto:support@dashsocial.com) # Monitor brand mentions with the Social Listening API Source: https://developer.dashsocial.com/guides/social-listening/monitor-brand-mentions-with-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} 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. ## 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" } ] } ```