Get post performance data across all 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:

Campaign Performance Review

Pull all posts published during a campaign window to analyze impact over time.

UGC Engagement Analysis

Filter by source type to analyze performance of user-generated content separately.

Platform-Based Filtering

Fetch media from a single social platform to create focused reports or dashboards.

Media Insights

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 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 for detailed information. Here is an example request with the appropriate filters:

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:

Instagram

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

Facebook

Value	Description
`FACEBOOK_OWNED`	Brand-owned content
`FACEBOOK_LINK`	Posts with external links
`FACEBOOK_TEXT_LINK`	Text with links
`FACEBOOK_TEXT`	Text-only posts

X.com

Value	Description
`TWITTER_OWNED`	Brand-owned content
`TWITTER_OWNED_LINK`	Posts with links
`TWITTER_OWNED_TEXT`	Text-only posts

TikTok

Value	Description
`TIKTOK_OWNED`	Brand-owned content

YouTube

Value	Description
`YOUTUBE_OWNED`	Brand-owned content

Other

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:

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.

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

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

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

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

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

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

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

Get Started

Reporting

Campaigns

Scheduler

Social Commerce

Social Listening

Community

Integration

MCP Server

Get post performance data across all channels

Use case examples

Campaign Performance Review

UGC Engagement Analysis

Platform-Based Filtering

Media Insights

Before you start

Setup and considerations

Rate limit

Data freshness

Implementation

Key query parameters

Full example

Sample response

Metrics

​Use case examples

Campaign Performance Review

UGC Engagement Analysis

Platform-Based Filtering

Media Insights

​Before you start

​Setup and considerations

​Rate limit

​Data freshness

​Implementation

​Key query parameters

​Full example

​Sample response

​Metrics

Use case examples

Before you start

Setup and considerations

Rate limit

Data freshness

Implementation

Key query parameters

Full example

Sample response

Metrics