> ## Documentation Index
> Fetch the complete documentation index at: https://developer.dashsocial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get 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:

<CardGroup cols={2}>
  <Card title="Campaign Performance Review">
    Pull all posts published during a campaign window to analyze impact over time.
  </Card>

  <Card title="UGC Engagement Analysis">
    Filter by source type to analyze performance of user-generated content separately.
  </Card>

  <Card title="Platform-Based Filtering">
    Fetch media from a single social platform to create focused reports or dashboards.
  </Card>

  <Card title="Media Insights">
    Compare performance across media types and surface high-performing assets.
  </Card>
</CardGroup>

## 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:

<AccordionGroup>
  <Accordion title="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         |
  </Accordion>

  <Accordion title="Pinterest">
    | Value             | Description         |
    | ----------------- | ------------------- |
    | `PINTEREST_OWNED` | Brand-owned content |
  </Accordion>

  <Accordion title="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           |
  </Accordion>

  <Accordion title="X.com">
    | Value                | Description         |
    | -------------------- | ------------------- |
    | `TWITTER_OWNED`      | Brand-owned content |
    | `TWITTER_OWNED_LINK` | Posts with links    |
    | `TWITTER_OWNED_TEXT` | Text-only posts     |
  </Accordion>

  <Accordion title="TikTok">
    | Value          | Description         |
    | -------------- | ------------------- |
    | `TIKTOK_OWNED` | Brand-owned content |
  </Accordion>

  <Accordion title="YouTube">
    | Value           | Description         |
    | --------------- | ------------------- |
    | `YOUTUBE_OWNED` | Brand-owned content |
  </Accordion>

  <Accordion title="Other">
    | Value      | Description |
    | ---------- | ----------- |
    | `UPLOADED` | Uploads     |
  </Accordion>
</AccordionGroup>

<Warning>
  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.
</Warning>

**`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:

<CodeGroup>
  ```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));
  ```
</CodeGroup>

**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.

<CodeGroup>
  ```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
      }
  }
  ```
</CodeGroup>

## Metrics

Select a platform to see the available metric names and their corresponding API key names.

<Tabs>
  <Tab title="Instagram">
    | 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`                             |
  </Tab>

  <Tab title="Instagram Stories">
    | 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`        |
  </Tab>

  <Tab title="Facebook">
    | 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`                     |
  </Tab>

  <Tab title="X.com">
    | 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`         |
  </Tab>

  <Tab title="TikTok">
    | 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`                             |
  </Tab>

  <Tab title="YouTube">
    | 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`                    |
  </Tab>
</Tabs>