Skip to main content
PUT
/
brands
/
{brand_id}
/
media
/
v2
Retrieve media
curl --request PUT \
  --url https://library-backend.dashsocial.com/brands/{brand_id}/media/v2 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filters": {
    "brand_media_types": [
      "INSTAGRAM_OWNED"
    ],
    "source_created_at": {
      "end": "2020-12-31",
      "start": "2020-01-01"
    },
    "instagram": {
      "caption_keywords": {
        "contain": [
          "<string>"
        ],
        "not_contain": [
          "<string>"
        ]
      },
      "features_account": "_flapjackie",
      "is_boosted": true,
      "post_type": "REEL",
      "post_types": [
        "REEL"
      ]
    },
    "instagram_story_frame": {
      "caption_keywords": {
        "contain": [
          "<string>"
        ],
        "not_contain": [
          "<string>"
        ]
      },
      "contain_swipe_up_link": true
    },
    "instagram_ugc": {
      "is_riq": true,
      "post_types": [
        "REEL"
      ],
      "ugc_media_type": "MENTIONED"
    },
    "instagram_story_ugc": {
      "is_riq": true,
      "post_types": [
        "REEL"
      ],
      "ugc_media_type": "MENTIONED"
    },
    "facebook": {
      "caption_keywords": {
        "contain": [
          "<string>"
        ],
        "not_contain": [
          "<string>"
        ]
      },
      "is_boosted": true,
      "post_types": [
        "VIDEO"
      ]
    },
    "tiktok": {
      "caption_keywords": {
        "contain": [
          "<string>"
        ],
        "not_contain": [
          "<string>"
        ]
      },
      "distribution_type": "ORGANIC",
      "media_type": [
        "VIDEO"
      ]
    },
    "tiktok_ugc": {
      "is_hashtag": true
    },
    "tiktok_ad": {
      "source_campaign_ids": [
        "123"
      ]
    },
    "pinterest": {
      "is_video": true,
      "pin_board_privacy": "public",
      "post_types": [
        "video"
      ]
    },
    "twitter": {
      "caption_keywords": {
        "contain": [
          "<string>"
        ],
        "not_contain": [
          "<string>"
        ]
      },
      "is_dark_post": true,
      "post_types": [
        "VIDEO"
      ]
    },
    "youtube": {
      "caption_keywords": {
        "contain": [
          "<string>"
        ],
        "not_contain": [
          "<string>"
        ]
      },
      "post_types": [
        "LIVE"
      ],
      "privacy_status": [
        "PRIVATE"
      ]
    },
    "linkedin": {
      "caption_keywords": {
        "contain": [
          "<string>"
        ],
        "not_contain": [
          "<string>"
        ]
      },
      "post_types": [
        "IMAGE",
        "VIDEO"
      ]
    },
    "threads": {
      "caption_keywords": {
        "contain": [
          "<string>"
        ],
        "not_contain": [
          "<string>"
        ]
      },
      "post_types": [
        "IMAGE",
        "VIDEO"
      ]
    },
    "snapchat": {
      "asset_types": [
        "STORY",
        "SAVED_STORY",
        "SPOTLIGHT",
        "SNAP"
      ],
      "caption_keywords": {
        "contain": [
          "<string>"
        ],
        "not_contain": [
          "<string>"
        ]
      },
      "parent_story_source_id": "ac234340-eb80-5439-9906-8672bb73075c"
    },
    "content_tags": [
      "Tag 1",
      "Tag 2"
    ],
    "content_tag_match_type": "ANY",
    "ai_generated": {
      "media_types": [
        "IMAGE"
      ]
    },
    "boards": [
      1234,
      4567
    ],
    "brand_ids": [
      144,
      1
    ],
    "campaign_ids": [
      1234,
      4567
    ],
    "campaigns": [
      123,
      456
    ],
    "campaigns_post_type": "VIDEO",
    "caption_is_negative": true,
    "caption_is_neutral": true,
    "caption_is_positive": true,
    "caption_is_question": true,
    "color": "red",
    "colors": [
      "red"
    ],
    "comments_are_negative": true,
    "comments_are_neutral": true,
    "comments_are_positive": true,
    "content_rights_requested_by": "12345",
    "content_rights_requested_date": {
      "end": "2020-12-31",
      "start": "2020-01-01"
    },
    "content_rights_type": [
      "APPROVED",
      "REQUESTED"
    ],
    "excluded_channels": [],
    "excluded_media_ids": [
      1234,
      4567
    ],
    "galleries": [
      1234,
      4567
    ],
    "image_data": "data:image/jpeg;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7",
    "include_disconnected_story_ugc": true,
    "indication_filter": {
      "indications": [
        "<string>"
      ],
      "operator": "AND"
    },
    "media_id": 123,
    "media_types": [
      "VIDEO"
    ],
    "prediction": {
      "max": 0.85,
      "min": 0.5
    },
    "ratio": "SQUARE",
    "ratios": [
      "SQUARE"
    ],
    "rights_approved": true,
    "scope_platform_filters": true,
    "search_term": "<string>",
    "search_terms": true,
    "size": "800x600",
    "source_account_ids": [
      "123456789",
      "987654321"
    ],
    "source_ids": [
      "1234",
      "4567"
    ],
    "uploads": {
      "media_types": [
        "VIDEO"
      ]
    }
  },
  "limit": 100,
  "offset": 0,
  "sort_fields": [
    "-DATE",
    "-INSTAGRAM_TOTAL_ENGAGEMENTS"
  ],
  "sort": "-DATE",
  "ids": [
    1234,
    4567
  ],
  "include_creator": false,
  "include_instagram_users": true,
  "collapse_field": "source_id",
  "campaign_creator_filters_options": {
    "only_excluded_media": false,
    "show_excluded_media": false
  }
}
'
{
  "data": [
    {
      "brand_id": 123,
      "brand_media_id": 123,
      "brand_media_status": "<string>",
      "callback_socket_id": "<string>",
      "can_publish_within": {
        "end": "<string>",
        "start": "<string>"
      },
      "caption_question": {
        "is_question": true,
        "user_overridden": true
      },
      "caption_sentiment": {
        "is_negative": true,
        "is_neutral": true,
        "is_positive": true,
        "user_overridden": true
      },
      "collections": {},
      "comment_sentiment": {
        "is_negative": true,
        "is_neutral": true,
        "is_positive": true,
        "user_overridden": true
      },
      "community_engagement": 123,
      "content_rights_expiry_date": "2023-11-07T05:31:56Z",
      "content_rights_requested_by": "<string>",
      "content_rights_requested_date": "2023-11-07T05:31:56Z",
      "content_tags": [
        "Tag 1",
        "Tag 2"
      ],
      "created_at": "2023-11-07T05:31:56Z",
      "creator": {
        "avatar_url": "<string>",
        "handle": "<string>"
      },
      "custom_metrics": [
        {
          "aggregation": "<string>",
          "description": "<string>",
          "formula": "<string>",
          "id": 123,
          "metric_format": "<string>",
          "name": "<string>",
          "value": 123
        }
      ],
      "facebook": {},
      "id": 123,
      "image": {
        "sizes": {
          "original": {
            "url": "<string>",
            "height": 123,
            "size": 123,
            "width": 123
          },
          "medium_square": {
            "url": "<string>",
            "height": 123,
            "size": 123,
            "width": 123
          },
          "original_converted": {
            "url": "<string>",
            "height": 123,
            "size": 123,
            "width": 123
          },
          "small": {
            "url": "<string>",
            "height": 123,
            "size": 123,
            "width": 123
          },
          "small_square": {
            "url": "<string>",
            "height": 123,
            "size": 123,
            "width": 123
          }
        },
        "editor_data": {
          "aspect_ratio": "<string>",
          "canvas_data": {
            "height": 123,
            "left": 123,
            "natural_height": 123,
            "natural_width": 123,
            "top": 123,
            "width": 123
          },
          "zoom_value": 123
        },
        "transforms": {
          "crop": {
            "height": 123,
            "width": 123,
            "x": 123,
            "y": 123
          },
          "parent_media_id": 123
        }
      },
      "instagram": {},
      "instagram_ads": {},
      "instagram_story": {},
      "instagram_story_frame": {},
      "instagram_user": {},
      "likeshop": {
        "clicks": 123,
        "links": "<string>",
        "tiktok_clicks": 123
      },
      "linkedin": {},
      "media_group": 123,
      "meta": {
        "filename": "<string>",
        "last_modified_at": "<string>",
        "uploaded_by": 123
      },
      "pinterest": {},
      "predictions": {
        "ad_engagement": 123,
        "conversions": 123,
        "engagement": 123,
        "link_clicks": 123
      },
      "snapchat": {},
      "source_account_id": "<string>",
      "source_created_at": "2023-11-07T05:31:56Z",
      "source_id": "<string>",
      "threads": {},
      "tiktok": {},
      "tiktok_ad": {},
      "twitter": {},
      "updated_at": "2023-11-07T05:31:56Z",
      "variants": [],
      "video": {
        "sizes": {
          "original": {
            "url": "<string>",
            "height": 123,
            "size": 123,
            "width": 123
          },
          "medium_square": {
            "url": "<string>",
            "height": 123,
            "size": 123,
            "width": 123
          },
          "original_converted": {
            "url": "<string>",
            "height": 123,
            "size": 123,
            "width": 123
          },
          "small": {
            "url": "<string>",
            "height": 123,
            "size": 123,
            "width": 123
          },
          "small_square": {
            "url": "<string>",
            "height": 123,
            "size": 123,
            "width": 123
          }
        },
        "duration": 123,
        "editor_data": {
          "aspect_ratio": "<string>"
        },
        "frame_rate": 123,
        "thumbnails": {
          "medium_square": {
            "url": "<string>",
            "height": 123,
            "size": 123,
            "width": 123
          },
          "original": {
            "url": "<string>",
            "height": 123,
            "size": 123,
            "width": 123
          },
          "original_converted": {
            "url": "<string>",
            "height": 123,
            "size": 123,
            "width": 123
          },
          "small": {
            "url": "<string>",
            "height": 123,
            "size": 123,
            "width": 123
          },
          "small_square": {
            "url": "<string>",
            "height": 123,
            "size": 123,
            "width": 123
          }
        },
        "transforms": {
          "crop": {
            "height": 123,
            "width": 123,
            "x": 123,
            "y": 123
          },
          "disable_audio_track": true,
          "parent_media_id": 123,
          "trim": {
            "end_time": 123,
            "start_time": 123
          }
        },
        "video_conversion_warnings": "<unknown>"
      },
      "video_predictions": {
        "engagement": [
          123
        ]
      },
      "video_predictions_interval_sec": 123,
      "video_suggested_thumbnail_list": [
        {
          "frame_position": 123,
          "index": 123,
          "predictions": {
            "engagement": 123
          },
          "url": "<string>"
        }
      ],
      "visual_features": "<string>",
      "youtube": {}
    }
  ],
  "paging": {
    "count": 123,
    "next": "<string>",
    "previous": "<string>"
  }
}

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.

Need help getting started? Check out the Get post performance data across all channels guide for use cases, filters, and sample responses.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
brand_id
integer<int32>
required

The Dash Social assigned ID of the brand.

Query Parameters

​
limit
integer
default:100

Number of results to return in a single response.

Required range: 0 <= x <= 1000
​
offset
integer
default:0

The offset of the first result to be returned.

Required range: x >= 0
​
ids
integer[]

Comma-separated list of IDs to return.

Example:
[812371, 828318]
​
include
enum<string>[]

Comma-separated list of optional fields to include.

Available options:
predictions,
source_data,
comment_sentiment,
visual_features
Example:
["predictions"]
​
exclude
enum<string>[]

Comma-separated list of optional fields to exclude.

Available options:
predictions,
source_data,
comment_sentiment,
visual_features
Example:
["source_data"]
​
next_token
string

Next token for deep pagination

Example:

"123123123,321321321"

Body

application/json
​
filters
object
​
limit
integer
default:100

Number of results to return in a single response.

Required range: 0 <= x <= 1000
​
offset
integer
default:0

The offset of the first result to be returned.

Required range: x >= 0
​
sort_fields
enum<string>[]

List of sort fields to apply. Prefix any value with - for descending order (e.g., -DATE). For platform-specific sorting, use {PLATFORM}_{METRIC} (e.g., -INSTAGRAM_TOTAL_ENGAGEMENTS, -TIKTOK_VIEWS, -FACEBOOK_TOTAL_ENGAGEMENTS). Common platform prefixes: INSTAGRAM_, FACEBOOK_, TIKTOK_, TWITTER_, PINTEREST_, YOUTUBE_, LINKEDIN_, SNAPCHAT_, THREADS_.

Sort field. Prefix with - for descending order.

Available options:
DATE,
RELEVANCE,
PERFORMANCE,
LIKESHOP_CLICKS,
CROSS_CHANNEL_VIDEO_VIEWS,
CROSS_CHANNEL_ENGAGEMENT_RATE,
CROSS_CHANNEL_IMPRESSIONS,
CROSS_CHANNEL_ENTERTAINMENT_SCORE,
CROSS_CHANNEL_TOTAL_ENGAGEMENTS,
CROSS_CHANNEL_EMV,
CROSS_CHANNEL_EFFECTIVENESS,
CROSS_CHANNEL_REACH,
CROSS_CHANNEL_SHARES,
CONTENT_RIGHTS_EXPIRY_DATE,
CONTENT_RIGHTS_REQUESTED_DATE
Example:
["-DATE", "-INSTAGRAM_TOTAL_ENGAGEMENTS"]
​
sort
enum<string>

Sort field for results. Prefix with - for descending order (e.g., -DATE). For platform-specific sorting, use the format {PLATFORM}_{METRIC} (e.g., -INSTAGRAM_TOTAL_ENGAGEMENTS, -TIKTOK_VIEWS). Deprecated in favor of sort_fields.

Available options:
DATE,
RELEVANCE,
PERFORMANCE,
LIKESHOP_CLICKS,
CROSS_CHANNEL_VIDEO_VIEWS,
CROSS_CHANNEL_ENGAGEMENT_RATE,
CROSS_CHANNEL_IMPRESSIONS,
CROSS_CHANNEL_ENTERTAINMENT_SCORE,
CROSS_CHANNEL_TOTAL_ENGAGEMENTS,
CROSS_CHANNEL_EMV,
CROSS_CHANNEL_EFFECTIVENESS,
CROSS_CHANNEL_REACH,
CROSS_CHANNEL_SHARES,
CONTENT_RIGHTS_EXPIRY_DATE,
CONTENT_RIGHTS_REQUESTED_DATE
Example:

"-DATE"

​
ids
integer[]

Array of media ids to return

Example:
[1234, 4567]
​
include_creator
boolean
default:false

Should include creator info

​
include_instagram_users
boolean

Should include instagram users

​
collapse_field
string

Field used to collapse hits (used to avoid duplicate posts)

Example:

"source_id"

​
campaign_creator_filters_options
object

When passing in a list of campaign IDs as a filter, these are options on how to apply the campaign's creator filters

Response

OK

​
data
object[]

List of MediaV2 Object.

​
paging
object

Paging object.