Response Types


The API returns a JSON document made up of several JSON objects defined in the following tables. The Required column denotes which fields are always present and which fields are optional based on the data being returned. URLs, where used, always include the protocol (http or https).

Top level response

dataThe actual data results. Either a Media Page Data object or a single Media Item object.Yes
metadataObject with trace identifiers and diagnostic info.Yes
errorObject with any error info.No
pagingObject with cursors and prev/next links if applicable.No

Media Page Data

itemsList of 0 to N media item results.Yes
totalCountNumber of total results available in the query. Use the "after" paging cursor to fetch more results.Yes

Media Item

idUniquely identifies a media item. These are stable across requests and can be used in the GET Media Item API.Yes
sourceSource object that describes where the content originated.Yes
labelsList of 0 or more strings that represent user-defined labels added in the Social Commerce App.Yes
mediaMedia object that gives the type and links to the underlying media.No
productsList of 0 or more Product objects.Yes

Media Item Source

typeThe social network where the content was originally posted: pinterest, facebook, instagram, twitter, tumblr. If the content did not come from a social network, it will not have info like user, link, caption, etc.Yes
postedTimestampEpoch timestamp (seconds) when the content was originally posted to the social network.Yes
userUser object describing details of the content post author.No
user.usernameUser's username.No
user.linkUser's profile link.No
user.imageUser's profile avatar with the original, small, medium, and square image variations.No
user.followerCountUser's follower count.No
user.followingCountUser's following count.No
linkLink to the post on the social network.No
captionString caption.No
commentCountApproximate number of comments the original post received on the social network.No
likeCountApproximate number of likes the original post received on the social network.No

Media Item Media

typeString enumeration: photo, gif, video.Yes
originalThe original media contents.Yes
small, medium, large, extraLargeVarious sizes of the image. Not provided for gif media types.No
smallSquare, mediumSquare, largeSquare, extraLargeSquareVarious square smart cropped sizes of the image. Not provided for gif media types. Smart cropping looks at the features and spatially tagged products to produce an optimal crop. More info in this blog post.Yes

Media Item Product

idUniquely identifies a product in the Social Commerce platform. It does not have meaning within the brand's product catalog.Yes
nameName or Title of the productYes
imagesList of 1 or more images for the product. Each image has different size and square smart cropped variations.Yes
linkLink to the product page or other destination URL.Yes
price.displayDisplay price (value and currency) of the product. This comes directly from the brand's product feed.No
metadataJSON object (key/value pairs) of various product metadata (e.g. productId, category, brand, manufacturer, sale_price, color, etc.).No
spatialTagJSON object with x, y, and label fields describing the spatial tag. x and y are floating point numbers defining the percent location of the tag on the original (or resized) media from the top/left corner.No