Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.dashsocial.com/llms.txt

Use this file to discover all available pages before exploring further.

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:
ValueDescription
INSTAGRAM_OWNEDBrand-owned content
INSTAGRAM_UGCUGC
INSTAGRAM_OTHERCompetitor content
INSTAGRAM_OWNED_IGTVBrand-owned IGTV
INSTAGRAM_UGC_IGTVUGC IGTV
INSTAGRAM_OTHER_IGTVCompetitor IGTV
INSTAGRAM_STORYBrand-owned stories
INSTAGRAM_STORY_UGCUGC stories
ValueDescription
PINTEREST_OWNEDBrand-owned content
ValueDescription
FACEBOOK_OWNEDBrand-owned content
FACEBOOK_LINKPosts with external links
FACEBOOK_TEXT_LINKText with links
FACEBOOK_TEXTText-only posts
ValueDescription
TWITTER_OWNEDBrand-owned content
TWITTER_OWNED_LINKPosts with links
TWITTER_OWNED_TEXTText-only posts
ValueDescription
TIKTOK_OWNEDBrand-owned content
ValueDescription
YOUTUBE_OWNEDBrand-owned content
ValueDescription
UPLOADEDUploads
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
    }
}

Metrics

Select a platform to see the available metric names and their corresponding API key names.
Metric nameAPI key name
Amount Spent - Promotedamount_spent
Clicks - Promotedclicks
Cost Per ThruPlay - Promotedcost_per_thruplay
CPC - Promotedcpc
CPM - Promotedcpm
CTR - Promotedctr
Effectiveness - Organiceffectiveness
Engagement Rate - Organic (Impressions)engagement_rate_impressions
Engagement Rate - Organic (Followers)engagement_rate_public
Entertainment Scoreentertainment_score
Impressions - Organicimpressions
Likes - Organiclike_count
LikeShop Clickslikeshop.clicks
Reach - Totalpaid_and_organic_reach
Saves - Totalpaid_and_organic_saved
Shares - Totalpaid_and_organic_shares
Engagement Rate - Promoted (Impressions)paid_engagement_rate
Impressions - Promotedpaid_impressions
Likes - Promotedpaid_likes
Reach - Promotedpaid_reach
Saves - Promotedpaid_saved
Shares - Promotedpaid_shares
Video Views - Promotedpaid_video_views
Bio Link Clicks - Organicprofile_activity.bio_link_clicked
Calls - Organicprofile_activity.calls
Directions - Organicprofile_activity.direction
Emails - Organicprofile_activity.email
Other - Organicprofile_activity.other
Profile Clicks - Organicprofile_activity.total
Profile Visits - Organicprofile_visits
Reach - Organicreach
Replays - Organicreplays
Saves - Organicsaved
Shares - Organicshares
Engagements - Totalsum_total_engagements
ThruPlays - Promotedthruplays
Comments - Totaltotal_comments
Engagementstotal_engagement
Impressions - Totaltotal_impressions
Likes - Totaltotal_likes
All Plays - Organictotal_plays
Total Time Viewed - Organictotal_time_viewed_sec
Plays - Totaltotal_video_views
Video Plays 100% - Promotedvideo_plays_100
Video Plays 25% - Promotedvideo_plays_25
Video Plays 50% - Promotedvideo_plays_50
Video Plays 75% - Promotedvideo_plays_75
Viewsviews