SocialCrawl
Unified schema

Post schema

The unified SocialCrawl post schema. Every field, its type, per-platform availability, and a machine-readable JSON Schema, generated from the canonical Zod source.

Every SocialCrawl endpoint that returns a post gives you this exact shape, whatever the source platform. Write your parser once and the same code reads post data from every platform below. That is the unified schema: one contract instead of a dozen raw upstream formats.

Field reference

FieldTypeNullableDescription
idstringNoPlatform-specific post ID (always a string; numeric upstream IDs are stringified)
urlstringYesDirect URL to the post on the source platform
content.textstringYesPost caption, description, or text content
content.media_urlsstring or string[]YesURL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.
content.thumbnail_urlstringYesURL to thumbnail image
content.duration_secondsnumberYesVideo/clip duration in seconds (null for non-video posts)
author.usernamestringYesAuthor username
author.display_namestringYesAuthor display name
author.avatar_urlstringYesURL to author profile picture
author.verifiedbooleanYesWhether the author account is verified
engagement.viewsnumberYesView count (if available). For Instagram video/reels this is the play count: the headline 'Views' the IG app shows. Instagram removed per-post play counts from its public web pages in August 2026, so GET /v1/instagram/post now fills the count automatically from a second source within the same call: videos and reels keep a numeric views with no extra endpoint or workaround. Note: since mid-July 2026 Instagram's play count is Instagram-only. It no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via /v1/facebook/post.
engagement.likesnumberYesLike / reaction count
engagement.commentsnumberYesComment count. Note: on GET /v1/instagram/post this is Instagram's edge_media_to_parent_comment.count (top-level comments); the IG list endpoints report the mobile comment_count total (includes replies). Both land on this same field.
engagement.sharesnumberYesShare / repost / retweet count. On Instagram this is reshare_count (the paper-plane Share / Send count) and it exists only on Instagram's mobile surface, so it is returned by /v1/instagram/post/stats, /v1/instagram/profile/reels/full, and /v1/instagram/profile/posts/full. The web-sourced Instagram list and search endpoints return null (never fabricated).
engagement.savesnumberYesSave / bookmark count. null on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated).
flags.nsfwbooleanYesNSFW flag (null when platform does not surface)
flags.spoilerbooleanYesSpoiler flag (null when platform does not surface)
flags.pinnedbooleanYesPinned-to-profile flag (null when platform does not surface)
flags.deletedbooleanNoWhether the post is tombstoned (always present)
flags.likes_hiddenbooleanYesPresent and true when the creator has hidden the like count. engagement.likes is null in that case (never the platform's decoy preview number). Absent on normal posts.
flags.comments_hiddenbooleanYesPresent and true when the upstream reports the comment count as hidden. engagement.comments is null in that case. Absent on normal posts.
flags.shares_hiddenbooleanYesTrue when the creator hides the share count, which is why engagement.shares is null.
flags.views_hiddenbooleanYesTrue when the creator hides the view count, which is why engagement.views is null.
flags.saves_hiddenbooleanYesTrue when the creator hides the save count, which is why engagement.saves is null.
published_atstring or numberYesPost creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under post.ext.published_at_epoch for one deprecation cycle.

Extension fields (ext)

Platform-specific passthrough. Each field is present only on the platforms that expose it and is absent everywhere else, so treat every ext.* field as optional. These carry the richer, per-platform signals the unified leaves cannot hold, and the join keys that chain endpoints together.

FieldTypeNullableDescription
ext.music_idstringYesTikTok music/clip id (exact string): pass to /v1/tiktok/song/videos?clipId= to find videos using the same sound
ext.matched_song_idstringYesTikTok only. The catalogue song TikTok matched the video's sound to, as an exact digit string. An official clip and the original sounds creators upload with it have different music_id values and the same matched_song_id, so group rows on it to count every use of one song. It is not a clipId: /v1/tiktok/song and /v1/tiktok/song/videos do not accept it. /v1/tiktok/search/music carries it on each sound, so a search on the song's title and artist, kept to the sounds with the same matched_song_id, gives the song's official sounds and their video_count. Absent when TikTok matched the sound to no song, and on rows served from a source that does not report the match.
ext.matched_song_titlestringYesTikTok only. The title of the song in matched_song_id. Absent when there is no matched song.
ext.matched_song_artiststringYesTikTok only. The artist of the song in matched_song_id, as TikTok's catalogue names it. Absent when there is no matched song.
ext.music_titlestringYesTikTok only. The title of the video's own sound (music_id). An uploaded sound is titled like original sound - <handle>; the song it plays, when TikTok recognised one, is matched_song_title.
ext.music_artiststringYesTikTok only. The artist TikTok shows for the video's own sound. On an original sound this is the uploader's display name, not the song's artist; use matched_song_artist for that.
ext.music_is_originalbooleanYesTikTok only. true when the video's sound is an original sound a creator uploaded, false when it is a catalogue track. Absent when the source does not say.
ext.author_idstringYesThe creator's platform-native numeric user id. On TikTok search and list items, pass to /v1/tiktok/profile?user_id= for the creator's current follower count (survives username changes). On Instagram /v1/instagram/search/reels, /v1/instagram/search/hashtag and /v1/instagram/location/posts items it is present on every row, accepted by /v1/instagram/profile/country?user_id= and /v1/instagram/basic-profile?userId=. On Facebook it appears when the upstream exposed a numeric actor id and no real handle.
ext.author_urlstringYesThe posting account's profile URL, so a matching post can be followed to its account. Present on /v1/facebook/search/posts rows: the vanity or /people/<name>/<id>/ URL when Facebook sends one, otherwise https://www.facebook.com/profile.php?id=<numeric id> built from the account id. Pass it as url to /v1/facebook/profile (or to /v1/prism/profiles with platform: facebook). Null when the row names neither an account URL nor a numeric account id. Absent on other endpoints.
ext.author_followersnumberYesThe creator's follower count as embedded in the search payload itself, when the search source happens to carry one. On Instagram search/reels it is null on a plain call, because Instagram stopped sending follower counts in its search payload in August 2026; send include=creator (or country) and it is filled from the creator's profile, 2 credits per creator looked up. It stays null when that lookup does not resolve.
ext.author_followingnumberYesAccounts the author follows, as of when the list source captured the row. Not live.
ext.author_posts_countnumberYesPosts the author has made, as of when the list source captured the row. Not live.
ext.author_locationstringYesThe free text the author wrote in their profile's location field, exactly as written (for example Johannesburg, South Africa). It is not a country code and is not checked; discover reads a country from it into geo.country (source: author_location). Present on X tweet and reply rows; null or absent when the author left it blank.
ext.in_reply_to_idstringYesId of the post this row replies to. Null when it answers nothing.
ext.in_reply_to_usernamestringYesHandle of the account this row replies to.
ext.conversation_idstringYesId of the post that opened the thread. Equals the row's own id on a top level post. X only.
ext.author_countrystringYesThe creator's country. On Instagram it is the country the creator declares on the About this account panel, as an ISO 3166-1 alpha-2 code (for example ES), and it is not where the post was filmed. It is present on /v1/instagram/search/reels when the request sends include=creator, include=country or country, and on /v1/instagram/search/hashtag and /v1/instagram/location/posts when it sends include=country, filled by looking the creator up. On YouTube rows joined with include=channel it is the channel's own country as an ISO 3166-1 alpha-2 code (for example ZA). Null when the platform publishes no country for the creator or the lookup did not resolve, and nothing is guessed; absent on a plain call.
ext.author_public_emailstringYesThe public contact email on the creator's profile. Present only on /v1/instagram/search/reels when the request sends include=creator, filled by looking the creator up. Null when the creator lists no public email or the lookup did not resolve; absent on a plain call.
ext.author_public_phonestringYesThe public contact phone number on the creator's profile. Present only on /v1/instagram/search/reels when the request sends include=creator, filled by looking the creator up. Null when the creator lists no public phone or the lookup did not resolve; absent on a plain call.
ext.download_countnumberYesHow many times the video has been saved to a device. TikTok only, and distinct from engagement.saves: a save keeps the video in a private collection on the platform, a download takes a copy off it, and TikTok counts the two separately. Present on TikTok post, search and post-list responses; absent everywhere else.
ext.regionstringYesTikTok only: the country TikTok registers the video to, as an ISO 3166-1 alpha-2 code (normally the creator's account country when they posted). It is not the viewer's country, not the region you requested, and not a language. On /v1/tiktok/trending, /v1/tiktok/search, /v1/tiktok/search/top, /v1/tiktok/profile/videos, /v1/tiktok/search/hashtag and /v1/tiktok/song/videos it is how you tell which rows are from a given country: filter on it when you need only that country. A row whose source omits the country stays null. The region request parameter still only sets the proxy.
ext.counts_approximatebooleanYes
ext.ran_as_adbooleanYes
ext.tagged_productsany[]YesThe TikTok Shop products tagged on the video. Empty when it tags none.
ext.subredditstringYesReddit subreddit name (search/list items): pass to /v1/reddit/subreddit/details?subreddit=
ext.titlestringYesThe post title on its own. Reddit only.
ext.selftextstringYesThe Reddit post body without the title. Null on link posts.
ext.link_domainstringYesHost a Reddit link post points at. Null on text posts and Reddit hosted media.
ext.upvote_rationumberYesReddit only: the share of a post's votes that are upvotes, as a fraction from 0 to 1 and usually close to 1 (six live rows measured 1, 1, 1, 0.86, 0.75, 1). Fractional despite the integer type this schema emits for every numeric leaf, the same caveat as author.ext.average_rating. Populated on /v1/reddit/search rows whose source carries it, and null everywhere else on Reddit including /v1/reddit/post and /v1/reddit/subreddit.
ext.flairstringYesThe post's link flair. Reddit only.
ext.content_languagestringYesThe language the platform itself tags the post with, when it sends one: Reddit's own language tag on Reddit lanes, and TikTok's caption-language tag (for example de) on /v1/tiktok/trending?feed=local. Null when the platform could not tell (Reddit und, TikTok un, common on short or emoji-only captions); absent where the source sends no tag. Never inferred from the text by us: that is post.computed.language.
ext.removedbooleanYes
ext.removed_bystringYes
ext.typestringYesItem type: pull_request or issue on GitHub lists; on LinkedIn feeds and post search, the kind of post in lower case, such as text, image, video, article, newsletter, document, poll, job, event or celebration. A poll can read text on a feed page whose answering source does not send the poll.
ext.content_typestringYesYouTube format: video, short, live, channel or playlist.
ext.ticker_symbolsstring[]YesInstruments the headline mentions, as identifiers such as GOOGL:NASDAQ. Pass one to /v1/finance/quote.
ext.video_view_countnumberYesInstagram's legacy 3-second-view count. Historical: Instagram stopped serving it in August 2026 (removed from its web post surface along with the web play count), so fresh /v1/instagram/post lookups no longer carry it and no source can restore it. Use engagement.views (the play count) instead.
ext.ig_play_countnumberYesInstagram-only play count (ig_play_count). Since mid-July 2026 Instagram's headline play count (engagement.views) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via /v1/facebook/post. Present on /v1/instagram/post/stats and, since the August 2026 views fix, on /v1/instagram/post for video posts.
ext.repost_countnumberYesReposts of the post. Instagram's two arrow repost count when include=saves is used.
ext.media_typestringYesMedia kind: image, video or carousel.
ext.text_truncatedbooleanYesTrue when content.text is a shortened summary and not the full note. Xiaohongshu only.
ext.ip_locationstringYesProvince the note was published from. Xiaohongshu only, not a self declared location.
ext.carousel_countnumberYesNumber of slides in an Instagram carousel. Present only when media_type is carousel.
ext.remix_countnumberYesHow many reels were made from this reel. Instagram only.
ext.audio_cluster_idstringYesInstagram's audio cluster for a reel, as an exact digit string: the id Instagram uses to group different uploads of the same sound. Present on /v1/instagram/audio/reels rows and on /v1/instagram/profile/reels with include=stats; absent on a row when it is not available and on every other surface.
ext.facebook_likesnumberYesInstagram only: the Facebook cross-post share that was EXCLUDED from engagement.likes on this row. A post shared to Facebook arrives from some sources with its Facebook likes already folded into the Instagram count, so the share is subtracted and published here, which keeps engagement.likes the Instagram-only figure instagram.com shows on the post. Add the two together for the combined number. Absent when the read carried no Facebook share, and absent on a post whose owner hides the like count, because nothing can be subtracted from a null. A response that excluded a share also carries a note in data._warnings.
ext.facebook_commentsnumberYesInstagram only: the Facebook cross-post share that was EXCLUDED from engagement.comments on this row, the comment counterpart of post.ext.facebook_likes. Each leaf appears only for the count it actually changed, so a post whose likes are hidden but whose comments were reconciled carries this one alone.
ext.instagram_viewsnumberYesInstagram only: the Instagram-only play count of a video, the same figure on every Instagram endpoint. engagement.views keeps each endpoint's established meaning: on /v1/instagram/profile/reels, /v1/instagram/audio/reels, /v1/instagram/search/reels and /v1/instagram/search/hashtag it can include the post's Facebook cross-post views, while on /v1/instagram/post and /v1/instagram/post/stats it is Instagram-only. Read this leaf when you compare one post across endpoints. Absent on photos and when the source did not report the Instagram-only figure.
ext.facebook_viewsnumberYesInstagram only: the Facebook cross-post part of a video's play count, the counterpart of post.ext.instagram_views. Present only when the source reported the Facebook part, or a combined total above the Instagram figure. Absent does not mean zero: some sources report the Instagram figure alone even for a cross-posted video.
ext.published_at_epochnumberYesRaw Unix epoch for published_at (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 published_at string. Kept for one deprecation cycle for integrations pinned to the numeric form.
ext.usertagsstring[]YesHandles of the accounts tagged in the post, in the order the platform lists them.
ext.coauthorsobject[]YesInstagram collaborative posts (the native "Collab" feature). The full list of co-author accounts on the post, as { id, username, full_name, is_verified, profile_pic_url }. A collab post has ONE producer and appears in every co-author's grid, so post.author is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is post.author.username plus every username in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including /v1/instagram/post (its web source ships the field permanently empty, so use /v1/instagram/post/stats for a single post).
ext.music.idstringNoThe id of the sound or audio track.
ext.music.track_titlestringYesTitle of the sound or track.
ext.music.artiststringYesThe artist or account that made the sound.
ext.music.is_originalbooleanNoTrue when the sound is the creator's own original audio.
ext.use_countnumberYesTikTok sounds only: how many videos use this sound. It is the same number as post.engagement.views on this endpoint, labelled correctly, and it is not a play count.
ext.use_count_unitstringYesWhat use_count counts. Always videos.
ext.shares_sourcestringYesOn profile/reels/full, where this row's share count came from: mobile_list (the mobile list read) or post_detail (a read of the post itself). Null when no read returned one.
ext.engagement_sourcestringYesOn Facebook profile/reels/full: post_detail when this row's engagement counts were read from the post itself, null when no read returned them.
ext.sponsor_tagsstring[]YesInstagram only: the brand accounts the post tags as its paid partner, as usernames (["rolex"]). [] on a post with no partner tagged. Present on /v1/instagram/post/stats; absent on every other endpoint.
ext.sponsored_disclosedbooleanYesThe platform's own disclosure that the post is paid or promotional: on Instagram the paid-partnership label (is_paid_partnership) or a tagged brand partner, on TikTok the label TikTok shows viewers ("Paid partnership", "Commission paid", "Promotional content"), on LinkedIn the brand partnership label LinkedIn shows on the post. false when the post carries the flag unset, null when it carries none. Present on /v1/instagram/post/stats, /v1/instagram/profile/posts, /v1/instagram/profile/reels, /v1/instagram/search/reels, /v1/tiktok/profile/videos and /v1/tiktok/search, and on every post of the LinkedIn feeds (/v1/linkedin/profile/posts, /v1/linkedin/company/posts, /v1/linkedin/profile/posts/archive, /v1/linkedin/profile/reactions, /v1/linkedin/post/reposts and /v1/linkedin/group/posts), where it is null unless the source that answered reports the label; absent on every other endpoint.
ext.ai_labelstringYesThe platform's AI-content label on the post. On Instagram, the method Instagram reports: classifier_score_high (Instagram detected it, shown as "Likely made with AI"), ai_created or ai_edited (declared or detected as made or edited with AI); present on /v1/instagram/post/stats. On /v1/linkedin/search/posts and /v1/linkedin/search/hashtag, c2pa_ai_generated when an image's C2PA content credentials say it was made with AI (the record is in post.ext.content_credentials). Null when the post carries no AI label; absent on every other endpoint.
ext.story_mentionsstring[]YesInstagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. [] when it mentions nobody. Present on /v1/instagram/stories; absent on every other endpoint.
ext.story_linksstring[]YesInstagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. [] when the story has no link sticker. Present on /v1/instagram/stories and /v1/instagram/highlight/detail; absent on every other endpoint.
ext.story_reshared_postsstring[]YesInstagram stories only: the feed posts the story reshares, as post URLs (https://www.instagram.com/p/{shortcode}/, which /v1/instagram/post takes). [] when it reshares none. Present on /v1/instagram/stories; absent on every other endpoint.
ext.location.idstringYesThe place's id on the platform, as a string.
ext.location.namestringYesThe place's name.
ext.location.latnumberYesLatitude in degrees.
ext.location.lngnumberYesLongitude in degrees.
ext.mediaobject[]YesThe slides of an Instagram carousel, in order.
ext.top_commentsobject[]YesThe comments shown under an Instagram post on the web page.
ext.hashtagsstring[]YesHashtags parsed from the caption, lower cased without the #, each listed once in order.
ext.mentionsstring[]YesHandles mentioned in the caption, lower cased with the @, each listed once in order.
ext.mentioned_user_idsstring[]YesNumeric ids of the accounts TikTok links in the row, in order and once each. Null when none.
ext.quoted_post.idstringNoThe quoted post's id.
ext.quoted_post.urlstringNoLink to the quoted post.
ext.quoted_post.author.idstringNoThe author's id on the platform.
ext.quoted_post.author.usernamestringNoThe author's handle.
ext.quoted_post.author.display_namestringNoThe author's display name.
ext.quoted_post.author.verifiedbooleanNoWhether the platform marks the author as verified.
ext.quoted_post.textstringYesThe text of the quoted post.
ext.quoted_post.media_urlsstring[]YesLinks to the media attached to the quoted post.
ext.quoted_post.thumbnail_urlstringYesLink to a preview image of the quoted post.
ext.quoted_post.engagement.viewsnumberNoView count.
ext.quoted_post.engagement.likesnumberNoLike count.
ext.quoted_post.engagement.commentsnumberNoReply count.
ext.quoted_post.engagement.sharesnumberNoShare or repost count.
ext.quoted_post.engagement.savesnumberNoSave or bookmark count.
ext.quoted_post.published_atstringNoWhen the quoted post was published, as the platform reported it (usually ISO 8601).
ext.quoted_post.quote_countnumberNoHow many times the quoted post was quoted.
ext.retweeted_post.idstringNoThe original post's id.
ext.retweeted_post.urlstringNoLink to the original post.
ext.retweeted_post.author.idstringNoThe author's id on the platform.
ext.retweeted_post.author.usernamestringNoThe author's handle.
ext.retweeted_post.author.display_namestringNoThe author's display name.
ext.retweeted_post.author.verifiedbooleanNoWhether the platform marks the author as verified.
ext.retweeted_post.textstringYesThe text of the original post.
ext.retweeted_post.media_urlsstring[]YesLinks to the media attached to the original post.
ext.retweeted_post.thumbnail_urlstringYesLink to a preview image of the original post.
ext.retweeted_post.engagement.viewsnumberNoView count.
ext.retweeted_post.engagement.likesnumberNoLike count.
ext.retweeted_post.engagement.commentsnumberNoReply count.
ext.retweeted_post.engagement.sharesnumberNoShare or repost count.
ext.retweeted_post.engagement.savesnumberNoSave or bookmark count.
ext.retweeted_post.published_atstringNoWhen the original post was published, as the platform reported it (usually ISO 8601).
ext.retweeted_post.quote_countnumberNoHow many times the original post was quoted.
ext.quote_countnumberYesHow many times the post was quoted. X and Threads.
ext.all_media_urlsstring[]YesEvery media URL on the post in source order. Present only when there is more than one. X only.
ext.reaction_countsobject[]YesReaction counts by type.
ext.share_urnstringYesLinkedIn's share urn for the post.
ext.post_typestringYesThe activity type of a LinkedIn post, such as ugc or activity.
ext.activity_idstringYesOn a LinkedIn article, the id of the post that shares it. post/comments takes this id.
ext.published_at_precisionstringYesHow exactly published_at is known: hour or day on LinkedIn feeds, where the source only gives a relative age. Absent means the time is exact.
ext.author_urnstringYesOpaque LinkedIn urn of the author. Joins to the /user endpoints without a lookup step.
ext.author_headlinestringYesThe author's profile headline. LinkedIn only.
ext.author_typestringYesWhether the author is a user or a company. LinkedIn only.
ext.is_repost_quotebooleanYesWhether a reshare added commentary (true) or was a plain repost (false). LinkedIn reposts only.
ext.article.titlestringNoTitle of the shared article.
ext.article.sourcestringNoThe article's publisher or domain.
ext.article.urlstringNoLink to the article.
ext.article.descriptionstringNoThe link card's summary of the article.
ext.reaction_typestringYesHow the member reacted, as LinkedIn's own rendered sentence (for example 'Bill Gates likes this'), localised. Profile reactions lane only.
ext.reacted_atstringYesWhen the member reacted, as an ISO 8601 UTC timestamp; published_at stays the post's own time. Profile reactions lane only.
ext.reactionstringYesThe member's reaction to the post as LinkedIn's code: LIKE, PRAISE, EMPATHY, APPRECIATION, INTEREST or ENTERTAINMENT. Null on a reaction to a comment, and where reaction_type holds a sentence that is not one of LinkedIn's English forms for a reaction to the post. Profile reactions lane only.
ext.reaction_activity_idstringYesThe id of the member's reaction itself on LinkedIn, the activity post.url links. Profile reactions lane only.
ext.mentioned_accountsobject[]YesThe accounts LinkedIn links in the post's text, in order. Our parse of @handles in the caption stays in mentions.
ext.text_entitiesobject[]YesThe linked ranges of the post's text.
ext.outbound_linksstring[]YesThe web links in the post's text, in order, each once. LinkedIn feeds and post search.
ext.is_editedbooleanYesTrue when LinkedIn shows the post as edited. LinkedIn feeds and post search.
ext.comments_disabledbooleanYesTrue when the author turned comments off on the post. LinkedIn feeds and post search.
ext.document.titlestringYesThe document's title.
ext.document.page_countnumberYesHow many pages it has.
ext.document.urlstringYesLink to the PDF.
ext.document.cover_urlstringYesLink to the image of its first page.
ext.poll.questionstringYesThe question.
ext.poll.optionsobject[]NoThe options, in the order LinkedIn shows them.
ext.poll.total_votesnumberYesVotes cast across all options.
ext.poll.voter_countnumberYesHow many people voted, where the source reports it.
ext.poll.is_closedbooleanYesTrue when the poll has ended.
ext.poll.remainingstringYesTime left as LinkedIn words it, such as 14h left.
ext.job.idstringYesThe job's id, the one /v1/linkedin/job takes.
ext.job.titlestringYesThe job title.
ext.job.company_namestringYesThe hiring company.
ext.job.company_idstringYesThe company's numeric id.
ext.job.company_urlstringYesLink to the company page.
ext.job.company_logostringYesLink to the company's logo.
ext.job.locationstringYesWhere the job is.
ext.job.urlstringYesLink to the job.
ext.celebration.headlinestringYesThe card's headline, such as Starting a New Position.
ext.celebration.image_urlstringYesLink to the card image.
ext.newsletter.titlestringYesThe newsletter's name.
ext.newsletter.urlstringYesLink to the newsletter.
ext.reposted_by.typestringYesuser or company where known.
ext.reposted_by.idstringYesThe account's LinkedIn id where known.
ext.reposted_by.namestringYesDisplay name.
ext.reposted_by.usernamestringYesThe member's or page's slug.
ext.reposted_by.urlstringYesLink to the profile or page.
ext.reposted_atstringYesWhen the feed's member or page reposted this post, as an ISO 8601 UTC timestamp. LinkedIn feeds.
ext.author_websitestringYesThe link on the button in the author's profile header, such as their newsletter or website. LinkedIn feeds and post search.
ext.author_website_labelstringYesThe text of that button, for example View my newsletter. LinkedIn feeds and post search.
ext.aspect_rationumberYesA video's width divided by its height, so 0.5625 is 9:16. LinkedIn feeds and post search.
ext.author_is_premiumbooleanYesTrue when LinkedIn marks the author as a Premium member. Null otherwise: LinkedIn sends the mark only when it is true, so null does not mean the author is not Premium. LinkedIn post search.
ext.content_credentials.is_ai_generatedbooleanYesTrue when the credentials say the image was made with AI.
ext.content_credentials.issuerstringYesWho issued the signing certificate.
ext.content_credentials.signerstringYesWho signed the credentials, such as the tool that made the image.
ext.content_credentials.is_validbooleanYesTrue when the credentials verify.
ext.download_media_urlsobject[]YesPermanent links to the downloaded media. Present when the call asked for a download.
ext.tagsstring[]YesVideo tags set by the creator. YouTube only.
ext.categoryIdstringYesYouTube's category id, for example 10.
ext.categoryTitlestringYesName of the YouTube category.
ext.topicCategoriesstring[]YesWikipedia URLs for the video's topics. YouTube only.
ext.durationstringYesVideo length as an ISO 8601 duration, for example PT3M33S.
ext.licensestringYesLicence the video is published under, for example youtube or creativeCommon.
ext.madeForKidsbooleanYesWhether the video is marked as made for kids. YouTube only.
ext.defaultAudioLanguagestringYesLanguage of the video's audio track as a BCP 47 code.
ext.hasPaidProductPlacementbooleanYesWhether the video discloses a paid product placement. YouTube only.
ext.captionstringYesWhether the video has captions, as the string true or false. YouTube only.
ext.playback_availability.visibilitystringYespublic, unlisted or private, as YouTube reports it.
ext.playback_availability.age_restrictedbooleanYesWhether the video is age-restricted.
ext.playback_availability.members_onlybooleanYesWhether the video is for the channel's paying members only.
ext.playback_availability.family_safebooleanYesWhether YouTube marks the video family-safe.
ext.playback_availability.region_restrictedbooleanYesWhether the video is blocked in some countries.
ext.playback_availability.available_countriesstring[]YesThe ISO 3166-1 alpha-2 codes of the countries the video plays in, sorted.
ext.playback_availability.live_contentbooleanYesWhether the video is or was a live stream.
ext.playback_availability.live_nowbooleanYesWhether the video is live right now.
ext.playback_availability.upcomingbooleanYesWhether the video is a scheduled premiere or stream that has not started.
ext.playback_availability.comments_visiblebooleanYesWhether comments are shown on the video.
ext.playback_availability.ratings_enabledbooleanYesWhether likes are enabled on the video.
ext.positionnumberYesPosition of the item in the playlist, counting from 0.
ext.playlistIdstringYesId of the playlist the item belongs to.
ext.videoOwnerChannelIdstringYesChannel id of the video's owner. YouTube playlist items only.
ext.videoPublishedAtstringYesWhen the video was published, as an ISO 8601 time. YouTube playlist items only.
ext.descriptionstringYesDescription text from the source record.
ext.default_languagestringYesDefault language of the video's metadata as a BCP 47 code.
ext.localizationsobjectYesTranslated video titles and descriptions, keyed by language code. Present with include_localizations.
ext.playlist_item_idstringYesId of the playlist item itself, distinct from the video id in post.id.
ext.playlist_owner_channel_idstringYesChannel id of the playlist's owner, not necessarily the video's channel.
ext.playlist_owner_titlestringYesName of the playlist's owner.
ext.channel_idstringYesThe 24 character YouTube channel id (starts with UC). Used because these rows carry no handle.
ext.published_labelstringYesThe relative label the source showed instead of a date, for example 'Streamed 3 weeks ago'.
ext.published_precisionstringYesHow precise published_at is when the source gave only a relative label: minute, hour, day, week, month or year.
ext.title_maybe_translatedbooleanYesTrue when the title may be an English machine translation of a non English video title.
ext.video_countnumberYesNumber of videos in the playlist. It is not a view count.
ext.posts_countnumberYes/v1/instagram/hashtag only: the exact number of public posts Instagram counts under the hashtag. Live: it moves between calls minutes apart.
ext.commerce.priceanyNoThe item's price: a number on a marketplace listing, an object on a shop product.
ext.commerce.currencystringNoISO 4217 currency code of the price.
ext.commerce.price_formattedstringNoPrice formatted for display.
ext.commerce.strikethrough_price_formattedstringNoThe crossed-out previous price, formatted for display.
ext.commerce.descriptionstringNoThe listing's description.
ext.commerce.location_textstringNoWhere the item is, as text.
ext.commerce.latitudenumberNoLatitude of the item in degrees.
ext.commerce.longitudenumberNoLongitude of the item in degrees.
ext.commerce.category_idstringNoThe listing category's id.
ext.commerce.mileagenumberYesMileage, for vehicles.
ext.commerce.attributesobject[]NoListing attributes.
ext.commerce.delivery_typesstring[]NoHow the item can be handed over.
ext.commerce.availability_textstringYesAvailability, as text.
ext.commerce.listing_date_textstringNoWhen the item was listed, as the platform words it.
ext.commerce.is_soldbooleanNoTrue when the item has sold.
ext.commerce.is_livebooleanNoTrue when the listing is live.
ext.commerce.is_pendingbooleanNoTrue when a sale is pending.
ext.commerce.is_hiddenbooleanNoTrue when the listing is hidden.
ext.commerce.is_shipping_offeredbooleanNoTrue when the seller ships the item.
ext.commerce.is_buy_now_enabledbooleanNoTrue when the buyer can buy without messaging first.
ext.commerce.messaging_enabledbooleanNoTrue when buyers can message the seller.
ext.commerce.seller_idstringYesThe seller's id on the platform.
ext.commerce.seller_namestringYesThe seller's name.
ext.commerce.rating.scorenumberNoAverage rating.
ext.commerce.rating.review_countnumberNoHow many ratings it is based on.
ext.commerce.rating.averagenumberNoAverage rating (same value as score).
ext.commerce.rating.countnumberNoHow many ratings it is based on (same value as review_count).
ext.commerce.sold.sold_countnumberNoUnits sold so far.
ext.on_screen_textsstring[]YesText the creator typed onto the video with TikTok's text tool.
ext.topic_tagstringYesName of the topic a Threads post is filed under. Not a slug, so join on topic_tag_id.
ext.reshare_countnumberYesThe boosted reshare figure Threads shows in the app.
ext.dsp_idsobjectYesThe same track's ids on music stores, keyed by lowercase store name.
ext.topic_tag_idstringYesId of the Threads topic. Use it to join, not the topic name.
ext.amazon_shop_listsobject[]YesThe creator's curated idea lists.
ext.amazon_shop_trending_picksobject[]YesProducts the creator features as trending picks.
ext.amazon_shop_curationsobject[]YesShoppable post sets the creator curated.
ext.amazon_shop_socialsstring[]YesThe creator's profile URLs outside Amazon. Amazon Influencer Shop only.
ext.ad.page_idstringNoId of the advertiser's page.
ext.ad.page_profile_uristringNoLink to the advertiser's page.
ext.ad.page_like_countnumberNoFollowers or likes of the advertiser's page.
ext.ad.page_categoriesstring[]NoThe advertiser page's categories.
ext.ad.brand_namestringNoThe advertiser's name.
ext.ad.currencystringNoISO 4217 currency code of the spend figures.
ext.ad.spendanyNoSpend range the library reports. The shape differs by library and is null when it hides spend.
ext.ad.spentstringNoSpend as the library words it. Empty when not disclosed.
ext.ad.reach_estimateanyNoReach estimate the library reports. The shape differs by library and is null when it hides reach.
ext.ad.estimated_audiencestringNoAudience size band, such as 10K-100K.
ext.ad.publisher_platformsstring[]NoWhere the ad ran.
ext.ad.categoriesstring[]NoThe ad's content categories.
ext.ad.targeted_or_reached_countriesstring[]NoCountries the ad targeted or reached.
ext.ad.country_codeanyNoThe country or countries the ad ran in.
ext.ad.cta_textstringNoThe call-to-action button text.
ext.ad.cta_typestringNoThe call-to-action type, such as LEARN_MORE.
ext.ad.link_urlstringNoWhere the ad sends people.
ext.ad.landing_pagestringNoLanding page the ad opens.
ext.ad.landing_page_urlstringYesLanding page the ad opens.
ext.ad.profile_web_linkstringNoLink to the advertiser's profile.
ext.ad.is_activebooleanNoTrue when the ad is still running.
ext.ad.end_date_isostringNoWhen the ad stopped, ISO 8601.
ext.ad.last_shown_datenumberNoWhen the ad was last shown, Unix milliseconds.
ext.ad.display_formatstringNoThe ad's display format, such as DCO.
ext.ad.ad_formatstringYesThe ad's format.
ext.ad.titlestringNoThe ad's headline.
ext.ad.captionstringNoThe ad's caption.
ext.ad.video_hd_urlstringYesLink to the high-definition video.
ext.ad.video_sd_urlstringYesLink to the standard-definition video.
ext.ad.video_url_540pstringNoLink to the 540p video.
ext.ad.video_url_360pstringNoLink to the 360p video.
ext.ad.video_idstringNoThe video's id.
ext.ad.image_urlsstring[]NoLinks to the ad's images.
ext.ad.audit_statusstringNoThe library's review status code for the ad.
ext.ad.typestringNoThe library's ad type code.
ext.ad.sourcestringNoThe library the ad came from.
ext.ad.objectivesobject[]NoThe campaign objectives the advertiser chose.
ext.ad.objectivestringNoThe campaign objective's code.
ext.ad.industrystringNoThe industry the ad belongs to.
ext.ad.languagestringYesThe ad's language.
ext.ad.ctrnumberNoClick-through rate band, 0 to 1.
ext.ad.cost_scorenumberNoRelative cost score.
ext.ad.ranknumberNoThe ad's rank on the board it was read from.
ext.ad.like_tierstringYesLike-count tier.
ext.ad.is_spark_adbooleanYesTrue when the ad boosts an organic post.
ext.ad.period_daysnumberNoLength of the ranking window in days.
ext.apple_music.kindstringNoWhat the item is, such as album or songs.
ext.apple_music.track_countnumberNoHow many tracks an album has.
ext.apple_music.release_infostringNoRelease date, track count, duration and copyright as one text block.
ext.apple_music.artist_urlstringNoLink to the artist's page.
ext.apple_music.artist_idstringNoThe artist's id.
ext.apple_music.release_datestringNoRelease date, as YYYY-MM-DD.
ext.apple_music.genresobject[]NoGenres the item belongs to.
ext.apple_music.content_advisorystringYesContent advisory label, such as explicit.
ext.apple_music.track_numbernumberNoPosition of the track on its album.
ext.apple_music.explicitbooleanNoTrue when the track is marked explicit.
ext.feedback_idstringYesJoin key that /v1/facebook/post/comments takes to read the post's comments.
ext.question_idstringYesNaver KnowledgeiN (/v1/naver/kin/search) only: the question's id (Naver's docId), read from the row's link. Kin returns one row per answer, so several rows can share it; send group=question for one row per question.
ext.answer_nonumberYesNaver KnowledgeiN only: which answer of the question this row is (Naver's answerNo), read from the row's link.
ext.answer_nosnumber[]YesNaver KnowledgeiN with group=question only: every answer number of the question that was on the page, best-ranked first.
ext.published_at_eststringYesNaver KnowledgeiN only: the question's date ESTIMATED from its id (YYYY-MM-DD, Korea time), never a published date, so published_at stays null. Absent for questions older than the calibration table.
ext.date_basisstringYesHow post.ext.published_at_est was derived. kin_docid_estimate: interpolated from the question id against question pages whose posted date was read.
ext.event.descriptionstringNoThe event's description.
ext.event.start_timestampnumberNoWhen the event starts, in Unix seconds.
ext.event.end_timestampnumberYesWhen the event ends, in Unix seconds.
ext.event.time_textstringNoThe event time as the platform words it, with time zone.
ext.event.duration_textstringNoHow long the event lasts, as text.
ext.event.location_namestringNoName of the venue, or Online event.
ext.event.addressstringYesStreet address.
ext.event.citystringYesCity.
ext.event.latitudenumberYesLatitude of the venue in degrees.
ext.event.longitudenumberYesLongitude of the venue in degrees.
ext.event.hostsobject[]NoThe people or pages hosting the event.
ext.event.host_context_textstringNoThe host line, such as Event by ....
ext.event.categorystringNoThe event's category.
ext.event.is_onlinebooleanNoTrue when the event is online.
ext.event.is_canceledbooleanNoTrue when the event is cancelled.
ext.event.is_pastbooleanNoTrue when the event has already happened.
ext.event.privacystringNoWho can see the event, such as public.
ext.event.ticket_urlstringYesLink to buy tickets.
ext.event.attendance_countnumberNoTotal attendance figure.
ext.event.interested_countnumberNoPeople who marked themselves interested.
ext.event.going_countnumberNoPeople who said they are going.
ext.event.idstringYesThe event's LinkedIn id.
ext.event.namestringYesThe event's name.
ext.event.date_textstringYesWhen the event runs, as LinkedIn words it, with time zone.
ext.event.locationstringYesWhere the event is, or Online.
ext.event.urlstringYesLink to the event.
ext.event.banner_urlstringYesLink to the event's banner image.
ext.trend.ranknumberNoThe row's rank on the board.
ext.trend.country_codestringNoThe market the board covers, as a country code.
ext.trend.chartstringNoWhich chart the row ranks on, such as songs.
ext.trend.chart_titlestringNoThe chart's title in the board's language.
ext.trend.updated_atstringNoWhen the board was last refreshed, ISO 8601.
ext.trend.period_daysnumberNoLength of the ranking window in days.
ext.trend.postsnumberNoHow many posts used the item in the window.
ext.trend.viewsnumberNoViews the item earned in the window.
ext.trend.period_viewsnumberNoViews in the window.
ext.trend.organic_viewsnumberNoOrganic views in the window.
ext.trend.six_second_view_through_ratenumberNoShare of views that reached six seconds, 0 to 1.
ext.trend.engagement_ratenumberNoEngagement rate for the window, 0 to 1.
ext.trend.order_bystringNoThe sort the board was read with.
ext.trend.industrystringYesThe industry code the board covers.
ext.trend.industry_idstringYesThe industry's id.
ext.trend.industry_labelstringYesThe industry's name.
ext.trend.boardsobject[]NoEvery board the row ranks on, with its rank there.
ext.trend.popularity_curveobject[]NoDaily popularity values for the window.
ext.trend.top_creatorsobject[]NoCreators who used the item most in the window.
ext.trend.content_tagsstring[]NoTags describing the video's content.
ext.updated_atstringYesWhen the platform last changed the post, as opposed to when it was published.
ext.alt_textstringYesPinterest's machine caption of the image. Never the creator's own text.
ext.board_namestringYesName of the board the pin was saved to. Pinterest only.
ext.topic_labelsstring[]Yes
ext.story_expires_atstringYes
ext.numeric_idnumberYesGitHub's numeric REST id, beside the GraphQL node id in post.id.
ext.outbound_urlstringYesThe page a Pinterest pin saves. Absent when it saves none.
ext.search_result_idstringYesThe id Facebook's video search gave this result, as sent. On a reel result it is often another id, such as the post that carries the reel; post.id is always the id in the video's URL. Facebook video search only.
ext.group.idstringNoThe group's key, as its link spells it (the numeric id or the vanity name).
ext.group.urlstringNoCanonical link to the group.
ext.group.namestringYesThe group's name.
ext.group.membersnumberYesThe group's member count.

Platform availability

29 platforms return the Post shape. id, flags.deleted are never null on any platform. The fields below vary: yes means the platform populates it (the value may still be null); a blank means the platform never provides it, so it is always null.

Platformauthor.verifiedengagement.savescontent.duration_secondsengagement.sharesengagement.viewsauthor.avatar_urlcontent.media_urlsurlengagement.commentscontent.thumbnail_urlflags.pinnedengagement.likes
Amazonyesyesyes
Apple Musicyesyesyesyes
Blueskyyesyesyesyes
Douyinyesyesyesyesyesyesyesyesyesyesyes
Facebookyesyesyesyesyesyesyesyesyesyesyes
Gabyesyesyesyesyesyes
GitHubyesyesyesyesyesyes
Googleyesyesyesyes
Hacker Newsyesyesyes
Instagramyesyesyesyesyesyesyesyesyesyesyes
Kickyesyesyesyesyesyesyesyesyesyes
Kwaiyesyesyesyesyesyesyesyesyesyesyes
LinkedInyesyesyesyesyesyesyesyesyes
Naveryesyesyesyesyesyesyes
Pinterestyesyesyesyesyesyesyesyesyesyesyes
Product Huntyesyesyesyes
Quorayesyesyesyesyes
Reddityesyesyesyesyesyesyesyesyesyesyesyes
Rumbleyesyesyesyesyes
Spotifyyesyesyesyesyes
Telegramyesyesyesyesyes
Threadsyesyesyesyesyesyesyesyesyes
TikTokyesyesyesyesyesyesyesyesyesyesyesyes
Truth Socialyesyesyesyesyesyesyesyesyesyes
Twitchyesyesyesyesyesyesyesyesyesyes
Twitter/Xyesyesyesyesyesyesyesyesyesyes
Weiboyesyesyesyesyesyesyesyesyesyesyes
Xiaohongshuyesyesyesyesyesyesyesyesyesyes
YouTubeyesyesyesyesyesyesyesyes

Machine-readable schema

Validate responses programmatically against the JSON Schema (2020-12):

/schemas/post.json

Point a validator (Ajv, jsonschema, or your framework's) at that URL, or hand it to an agent so it can check the shape without a live call.

Returned by

Endpoints with the Post / PostList archetype return this shape:

Amazon · Apple Music · Bluesky · Douyin · Facebook · Gab · GitHub · Google · Hacker News · Instagram · Kick · Kwai · LinkedIn · Naver · Pinterest · Product Hunt · Quora · Reddit · Rumble · Spotify · Telegram · Threads · TikTok · Truth Social · Twitch · Twitter/X · Weibo · Xiaohongshu · YouTube

See how the same fields map to each platform's raw upstream names in the cross-platform field equivalence table.

On this page