InsightSocial APIUnified schema
Post
The unified post object. Every field, its type, and which of the 9 platforms fill it.
Any endpoint that returns a post returns it in this shape, whichever platform it came from. Write one parser and it reads posts from all 9 platforms.
Fields
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | No | The platform's ID for the post. Always a string, even when the platform uses numbers. |
url | string | Yes | Link to the post on the platform. |
content.text | string | Yes | Caption, description or body text. |
content.media_urls | string or string[] | Yes | Main media. A single URL for one photo or video, an array for a carousel. |
content.thumbnail_url | string | Yes | Thumbnail image. |
content.duration_seconds | integer | Yes | Length of a video or clip in seconds. null when the post is not a video. |
author.username | string | Yes | The author's handle. |
author.display_name | string | Yes | The author's display name. |
author.avatar_url | string | Yes | The author's profile picture. |
author.verified | boolean | Yes | Whether the author is verified. |
engagement.views | integer | Yes | Views where the platform shows them. On Instagram videos and reels this is the play count shown in the app, and it counts Instagram plays only, not views of a copy cross-posted to Facebook. Fetch the Facebook copy with /v1/facebook/post if you need both. |
engagement.likes | integer | Yes | Likes or reactions. |
engagement.comments | integer | Yes | Comment count. On /v1/instagram/post it counts top-level comments; the Instagram list endpoints count all comments including replies. Both use this field. |
engagement.shares | integer | Yes | Shares, reposts or retweets. On Instagram this is the Send count, available only from /v1/instagram/post/stats, /v1/instagram/profile/reels/full and /v1/instagram/profile/posts/full; other Instagram endpoints return null. |
engagement.saves | integer | Yes | Saves or bookmarks. |
flags.nsfw | boolean | Yes | Marked as adult content. null when the platform does not say. |
flags.spoiler | boolean | Yes | Marked as a spoiler. null when the platform does not say. |
flags.pinned | boolean | Yes | Pinned to the profile. null when the platform does not say. |
flags.deleted | boolean | No | The post has been deleted or removed. Always present. |
flags.likes_hidden | boolean | Yes | true when the creator hides the like count; engagement.likes is then null, never a placeholder number. Absent on ordinary posts. |
flags.comments_hidden | boolean | Yes | true when the comment count is reported as hidden; engagement.comments is then null. Absent on ordinary posts. |
flags.shares_hidden | boolean | Yes | true when the share count is hidden. |
flags.views_hidden | boolean | Yes | true when the view count is hidden. |
flags.saves_hidden | boolean | Yes | true when the save count is hidden. |
published_at | string or integer | Yes | When the post was published, as an ISO 8601 UTC string. If the platform sent a Unix timestamp, it is converted and the original number is kept in ext.published_at_epoch. |
Extension fields (ext)
Platform-specific extras. Each one appears only on platforms that provide it and is left out elsewhere, so treat all of them as optional. They hold detail the unified fields cannot, and the IDs that let you pass a result from one endpoint into the next.
| Field | Type | Nullable | Description |
|---|---|---|---|
ext.music_id | string | Yes | TikTok sound ID. Pass it to /v1/tiktok/song/videos?clipId= to find other videos using the same sound. |
ext.author_id | string | Yes | The creator's numeric platform ID. On TikTok search and list rows, /v1/tiktok/profile?user_id= accepts it and keeps working after a username change. On Instagram search/reels rows it is always present and works with /v1/instagram/basic-profile?userId=. On Facebook it appears when a numeric ID was available but no handle. |
ext.author_followers | integer | Yes | Follower count included in a search row, when that search carries one. Always null on Instagram rows now; call /v1/instagram/profile?handle= for the exact current count. |
ext.author_following | integer | Yes | Following count included in the row, when present. |
ext.author_posts_count | integer | Yes | The author's post count included in the row, when present. |
ext.download_count | integer | Yes | TikTok only. How many times the video was downloaded to a device. Separate from engagement.saves, which counts saves to an in-app collection. |
ext.region | string | Yes | TikTok only. The ISO 3166-1 alpha-2 country the video is registered to, usually the creator's account country. It is not the viewer's country or a language. On /v1/tiktok/trending, /v1/tiktok/search and /v1/tiktok/search/top, filter on it to keep rows from one country. |
ext.subreddit | string | Yes | Reddit subreddit name on search and list rows. Pass it to /v1/reddit/subreddit/details?subreddit=. |
ext.title | string | Yes | Post title, where the platform separates title from body. |
ext.selftext | string | Yes | Reddit text-post body. |
ext.upvote_ratio | integer | Yes | Reddit only. Share of votes that are upvotes, from 0 to 1. The value is a fraction even though the type says integer. Filled on /v1/reddit/search rows where available, null elsewhere. |
ext.flair | string | Yes | Reddit post flair. |
ext.content_language | string | Yes | The language the platform itself assigned to the post, when it sends one (Reddit's tag, or TikTok's caption tag on /v1/tiktok/trending?feed=local). null when the platform could not tell. Never inferred by us; our own detection is computed.language. |
ext.type | string | Yes | Platform's own post type. |
ext.content_type | string | Yes | Platform's own content type. |
ext.video_view_count | integer | Yes | Instagram's old 3-second view count. No longer served, so new lookups do not carry it. Use engagement.views. |
ext.ig_play_count | integer | Yes | Instagram's own play count, shown separately so you can tell it apart from any combined figure. Present on /v1/instagram/post/stats, and on /v1/instagram/post for videos. |
ext.repost_count | integer | Yes | Repost count, where it is separate from shares. |
ext.media_type | string | Yes | Platform's media type (photo, video, carousel and so on). |
ext.text_truncated | boolean | Yes | true when the text was cut short on this surface. |
ext.ip_location | string | Yes | Location the platform displays for the poster, where shown. |
ext.carousel_count | integer | Yes | Number of items in a carousel. |
ext.remix_count | integer | Yes | Number of remixes. |
ext.facebook_likes | integer | Yes | Instagram only. Facebook likes from a cross-post that were removed from engagement.likes, so that field matches what instagram.com shows. Add them back for a combined figure. Absent when nothing was removed or the like count is hidden. A response that removed anything also has a note in data._warnings. |
ext.facebook_comments | integer | Yes | Instagram only. The comment equivalent of ext.facebook_likes. Each of the two appears only for the count it changed. |
ext.published_at_epoch | integer | Yes | The original Unix timestamp (seconds or milliseconds) when the platform sent one and it was converted into published_at. |
ext.usertags | string[] | Yes | Accounts tagged in the post. |
ext.coauthors | string[] | Yes | Instagram Collab posts. Every co-author as { id, username, full_name, is_verified, profile_pic_url }. A Collab post has one creator but shows on every co-author's grid, so post.author may not be the profile you asked for. All accounts on the post are post.author.username plus each username here. An empty array means not a Collab. Absent where there is no signal, including on /v1/instagram/post; use /v1/instagram/post/stats for a single post. |
ext.music | string | Yes | Music or sound attached to the post. |
ext.sponsor_tags | string[] | Yes | Sponsor or paid-partnership tags. |
ext.location | string | Yes | Location tagged on the post. |
ext.quoted_post | string | Yes | Threads quote posts. The quoted post as { id, url, author: { id, username }, text, media_urls, thumbnail_url }. A quote post often has no text or media of its own, and what you see on its page belongs to the quoted post by another author. It stays here so content.* always describes the outer post. Absent on posts that are not quotes. |
ext.retweeted_post | string | Yes | Twitter/X: the original post behind a retweet. |
ext.quote_count | integer | Yes | Number of quote posts. |
ext.all_media_urls | string[] | Yes | Every media URL on the post. |
ext.reaction_counts | string[] | Yes | Counts broken down by reaction type. |
ext.share_urn | string | Yes | LinkedIn share URN. |
ext.post_type | string | Yes | Platform's post type. |
ext.activity_id | string | Yes | LinkedIn activity ID. |
ext.published_at_precision | string | Yes | How precise published_at is when the platform shows only a relative or rounded time. |
ext.author_urn | string | Yes | LinkedIn URN of the author. |
ext.author_headline | string | Yes | LinkedIn headline of the author. |
ext.author_type | string | Yes | Whether the LinkedIn author is a person or a company. |
ext.is_repost_quote | boolean | Yes | true when a repost adds its own commentary. |
ext.article | string | Yes | LinkedIn article attached to the post. |
ext.reaction_type | string | Yes | The reaction a member left, on reaction lists. |
ext.download_media_urls | string[] | Yes | Downloadable media URLs, when requested. |
ext.tags | string[] | Yes | Tags attached to the post. |
ext.categoryId | string | Yes | YouTube category ID. |
ext.categoryTitle | string | Yes | YouTube category name. |
ext.topicCategories | string[] | Yes | YouTube topic categories. |
ext.duration | string | Yes | YouTube duration in its original format. |
ext.license | string | Yes | YouTube license. |
ext.madeForKids | boolean | Yes | YouTube made-for-kids flag. |
ext.defaultAudioLanguage | string | Yes | YouTube default audio language. |
ext.hasPaidProductPlacement | boolean | Yes | YouTube paid product placement flag. |
ext.caption | string | Yes | YouTube caption status. |
ext.position | integer | Yes | Position in a YouTube playlist. |
ext.playlistId | string | Yes | YouTube playlist ID. |
ext.videoOwnerChannelId | string | Yes | Channel that owns a video in a playlist. |
ext.videoPublishedAt | string | Yes | When a playlist video was published. |
ext.description | string | Yes | Full description, where separate from content.text. |
ext.default_language | string | Yes | Default language set on the video. |
ext.playlist_item_id | string | Yes | YouTube playlist item ID. |
ext.playlist_owner_channel_id | string | Yes | Channel that owns the playlist. |
ext.playlist_owner_title | string | Yes | Name of the playlist owner. |
ext.channel_id | string | Yes | YouTube channel ID. |
ext.published_label | string | Yes | The relative time label the platform shows, such as "3 days ago". |
ext.published_precision | string | Yes | How precise the published time is. |
ext.video_count | integer | Yes | Number of videos, on playlist or collection rows. |
ext.commerce | string | Yes | Shopping or commerce details attached to the post. |
ext.on_screen_texts | string[] | Yes | Text shown on screen in the video. |
ext.topic_tag | string | Yes | Threads topic tag. |
ext.topic_tag_id | string | Yes | Threads topic tag ID. |
ext.reshare_count | integer | Yes | Reshare count, where reported separately. |
ext.ad | string | Yes | Facebook Ad Library details, on /v1/facebook/adlibrary/ad and /v1/facebook/adlibrary/company/ads rows: page_id, currency, spend, reach_estimate, publisher_platforms, categories, targeted_or_reached_countries, cta_text, cta_type, link_url, is_active, end_date_iso, display_format, title, video_hd_url, video_sd_url. Absent elsewhere. |
ext.feedback_id | string | Yes | Facebook feedback ID, used to fetch comments and replies. |
ext.event | string | Yes | Facebook event details, including interested_count, going_count, end_timestamp and ticket_url. |
ext.trend | string | Yes | TikTok trend-board data. On /v1/tiktok/hashtags/popular: rank, country_code, period_days, posts and views for the period (not lifetime), industry, industry_id, industry_label for the first board read (null for the overall board), boards listing every board the hashtag ranks on as { industry, industry_id, industry_label, rank }, popularity_curve as { date, value } with value 0 to 100 relative to the period's peak, and top_creators. On /v1/tiktok/videos/popular: rank, country_code, period_days, order_by, period_views, organic_views, engagement_rate, six_second_view_through_rate, content_tags. Absent elsewhere. |
ext.updated_at | string | Yes | When the post was last edited, where shown. |
Which platforms fill which fields
All 9 platforms return this shape. id and flags.deleted are never null. How to read the table: yes marks a field the platform is able to supply, though any single row can still have it null. An empty cell marks a field that platform never supplies, so expect null every time.
| Platform | author.verified | engagement.saves | engagement.shares | content.duration_seconds | engagement.views | author.avatar_url | engagement.comments | content.media_urls | url | engagement.likes | content.thumbnail_url | flags.pinned |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | |||
| yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | ||
| yes | yes | yes | yes | yes | yes | yes | yes | yes | ||||
| yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | ||
| yes | yes | yes | yes | yes | yes | yes | yes | yes | ||||
| Threads | yes | yes | yes | yes | yes | yes | yes | yes | yes | |||
| TikTok | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
| Twitter/X | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | ||
| YouTube | yes | yes | yes | yes | yes | yes | yes | yes |
Instagram saves come only from /v1/instagram/post/stats with include=saves. See Metric substitutions for the full list of per-platform nulls.
Returned by
Endpoints that return a post or a list of posts use this shape on:
Facebook · Instagram · LinkedIn · Pinterest · Reddit · Threads · TikTok · Twitter/X · YouTube
To see which native platform field feeds each unified field, read Field equivalence.