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
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | No | Platform-specific post ID (always a string; numeric upstream IDs are stringified) |
url | string | Yes | Direct URL to the post on the source platform |
content.text | string | Yes | Post caption, description, or text content |
content.media_urls | string or string[] | Yes | URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels. |
content.thumbnail_url | string | Yes | URL to thumbnail image |
content.duration_seconds | number | Yes | Video/clip duration in seconds (null for non-video posts) |
author.username | string | Yes | Author username |
author.display_name | string | Yes | Author display name |
author.avatar_url | string | Yes | URL to author profile picture |
author.verified | boolean | Yes | Whether the author account is verified |
engagement.views | number | Yes | View 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.likes | number | Yes | Like / reaction count |
engagement.comments | number | Yes | Comment 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.shares | number | Yes | Share / 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.saves | number | Yes | Save / bookmark count. null on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated). |
flags.nsfw | boolean | Yes | NSFW flag (null when platform does not surface) |
flags.spoiler | boolean | Yes | Spoiler flag (null when platform does not surface) |
flags.pinned | boolean | Yes | Pinned-to-profile flag (null when platform does not surface) |
flags.deleted | boolean | No | Whether the post is tombstoned (always present) |
flags.likes_hidden | boolean | Yes | Present 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_hidden | boolean | Yes | Present and true when the upstream reports the comment count as hidden. engagement.comments is null in that case. Absent on normal posts. |
flags.shares_hidden | boolean | Yes | True when the creator hides the share count, which is why engagement.shares is null. |
flags.views_hidden | boolean | Yes | True when the creator hides the view count, which is why engagement.views is null. |
flags.saves_hidden | boolean | Yes | True when the creator hides the save count, which is why engagement.saves is null. |
published_at | string or number | Yes | Post 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.
| Field | Type | Nullable | Description |
|---|---|---|---|
ext.music_id | string | Yes | TikTok music/clip id (exact string): pass to /v1/tiktok/song/videos?clipId= to find videos using the same sound |
ext.matched_song_id | string | Yes | TikTok 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_title | string | Yes | TikTok only. The title of the song in matched_song_id. Absent when there is no matched song. |
ext.matched_song_artist | string | Yes | TikTok 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_title | string | Yes | TikTok 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_artist | string | Yes | TikTok 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_original | boolean | Yes | TikTok 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_id | string | Yes | The 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_url | string | Yes | The 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_followers | number | Yes | The 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_following | number | Yes | Accounts the author follows, as of when the list source captured the row. Not live. |
ext.author_posts_count | number | Yes | Posts the author has made, as of when the list source captured the row. Not live. |
ext.author_location | string | Yes | The 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_id | string | Yes | Id of the post this row replies to. Null when it answers nothing. |
ext.in_reply_to_username | string | Yes | Handle of the account this row replies to. |
ext.conversation_id | string | Yes | Id of the post that opened the thread. Equals the row's own id on a top level post. X only. |
ext.author_country | string | Yes | The 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_email | string | Yes | The 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_phone | string | Yes | The 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_count | number | Yes | How 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.region | string | Yes | TikTok 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_approximate | boolean | Yes | |
ext.ran_as_ad | boolean | Yes | |
ext.tagged_products | any[] | Yes | The TikTok Shop products tagged on the video. Empty when it tags none. |
ext.subreddit | string | Yes | Reddit subreddit name (search/list items): pass to /v1/reddit/subreddit/details?subreddit= |
ext.title | string | Yes | The post title on its own. Reddit only. |
ext.selftext | string | Yes | The Reddit post body without the title. Null on link posts. |
ext.link_domain | string | Yes | Host a Reddit link post points at. Null on text posts and Reddit hosted media. |
ext.upvote_ratio | number | Yes | Reddit 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.flair | string | Yes | The post's link flair. Reddit only. |
ext.content_language | string | Yes | The 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.removed | boolean | Yes | |
ext.removed_by | string | Yes | |
ext.type | string | Yes | Item 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_type | string | Yes | YouTube format: video, short, live, channel or playlist. |
ext.ticker_symbols | string[] | Yes | Instruments the headline mentions, as identifiers such as GOOGL:NASDAQ. Pass one to /v1/finance/quote. |
ext.video_view_count | number | Yes | Instagram'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_count | number | Yes | Instagram-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_count | number | Yes | Reposts of the post. Instagram's two arrow repost count when include=saves is used. |
ext.media_type | string | Yes | Media kind: image, video or carousel. |
ext.text_truncated | boolean | Yes | True when content.text is a shortened summary and not the full note. Xiaohongshu only. |
ext.ip_location | string | Yes | Province the note was published from. Xiaohongshu only, not a self declared location. |
ext.carousel_count | number | Yes | Number of slides in an Instagram carousel. Present only when media_type is carousel. |
ext.remix_count | number | Yes | How many reels were made from this reel. Instagram only. |
ext.audio_cluster_id | string | Yes | Instagram'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_likes | number | Yes | Instagram 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_comments | number | Yes | Instagram 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_views | number | Yes | Instagram 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_views | number | Yes | Instagram 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_epoch | number | Yes | Raw 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.usertags | string[] | Yes | Handles of the accounts tagged in the post, in the order the platform lists them. |
ext.coauthors | object[] | Yes | Instagram 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.id | string | No | The id of the sound or audio track. |
ext.music.track_title | string | Yes | Title of the sound or track. |
ext.music.artist | string | Yes | The artist or account that made the sound. |
ext.music.is_original | boolean | No | True when the sound is the creator's own original audio. |
ext.use_count | number | Yes | TikTok 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_unit | string | Yes | What use_count counts. Always videos. |
ext.shares_source | string | Yes | On 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_source | string | Yes | On 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_tags | string[] | Yes | Instagram 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_disclosed | boolean | Yes | The 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_label | string | Yes | The 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_mentions | string[] | Yes | Instagram 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_links | string[] | Yes | Instagram 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_posts | string[] | Yes | Instagram 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.id | string | Yes | The place's id on the platform, as a string. |
ext.location.name | string | Yes | The place's name. |
ext.location.lat | number | Yes | Latitude in degrees. |
ext.location.lng | number | Yes | Longitude in degrees. |
ext.media | object[] | Yes | The slides of an Instagram carousel, in order. |
ext.top_comments | object[] | Yes | The comments shown under an Instagram post on the web page. |
ext.hashtags | string[] | Yes | Hashtags parsed from the caption, lower cased without the #, each listed once in order. |
ext.mentions | string[] | Yes | Handles mentioned in the caption, lower cased with the @, each listed once in order. |
ext.mentioned_user_ids | string[] | Yes | Numeric ids of the accounts TikTok links in the row, in order and once each. Null when none. |
ext.quoted_post.id | string | No | The quoted post's id. |
ext.quoted_post.url | string | No | Link to the quoted post. |
ext.quoted_post.author.id | string | No | The author's id on the platform. |
ext.quoted_post.author.username | string | No | The author's handle. |
ext.quoted_post.author.display_name | string | No | The author's display name. |
ext.quoted_post.author.verified | boolean | No | Whether the platform marks the author as verified. |
ext.quoted_post.text | string | Yes | The text of the quoted post. |
ext.quoted_post.media_urls | string[] | Yes | Links to the media attached to the quoted post. |
ext.quoted_post.thumbnail_url | string | Yes | Link to a preview image of the quoted post. |
ext.quoted_post.engagement.views | number | No | View count. |
ext.quoted_post.engagement.likes | number | No | Like count. |
ext.quoted_post.engagement.comments | number | No | Reply count. |
ext.quoted_post.engagement.shares | number | No | Share or repost count. |
ext.quoted_post.engagement.saves | number | No | Save or bookmark count. |
ext.quoted_post.published_at | string | No | When the quoted post was published, as the platform reported it (usually ISO 8601). |
ext.quoted_post.quote_count | number | No | How many times the quoted post was quoted. |
ext.retweeted_post.id | string | No | The original post's id. |
ext.retweeted_post.url | string | No | Link to the original post. |
ext.retweeted_post.author.id | string | No | The author's id on the platform. |
ext.retweeted_post.author.username | string | No | The author's handle. |
ext.retweeted_post.author.display_name | string | No | The author's display name. |
ext.retweeted_post.author.verified | boolean | No | Whether the platform marks the author as verified. |
ext.retweeted_post.text | string | Yes | The text of the original post. |
ext.retweeted_post.media_urls | string[] | Yes | Links to the media attached to the original post. |
ext.retweeted_post.thumbnail_url | string | Yes | Link to a preview image of the original post. |
ext.retweeted_post.engagement.views | number | No | View count. |
ext.retweeted_post.engagement.likes | number | No | Like count. |
ext.retweeted_post.engagement.comments | number | No | Reply count. |
ext.retweeted_post.engagement.shares | number | No | Share or repost count. |
ext.retweeted_post.engagement.saves | number | No | Save or bookmark count. |
ext.retweeted_post.published_at | string | No | When the original post was published, as the platform reported it (usually ISO 8601). |
ext.retweeted_post.quote_count | number | No | How many times the original post was quoted. |
ext.quote_count | number | Yes | How many times the post was quoted. X and Threads. |
ext.all_media_urls | string[] | Yes | Every media URL on the post in source order. Present only when there is more than one. X only. |
ext.reaction_counts | object[] | Yes | Reaction counts by type. |
ext.share_urn | string | Yes | LinkedIn's share urn for the post. |
ext.post_type | string | Yes | The activity type of a LinkedIn post, such as ugc or activity. |
ext.activity_id | string | Yes | On a LinkedIn article, the id of the post that shares it. post/comments takes this id. |
ext.published_at_precision | string | Yes | How 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_urn | string | Yes | Opaque LinkedIn urn of the author. Joins to the /user endpoints without a lookup step. |
ext.author_headline | string | Yes | The author's profile headline. LinkedIn only. |
ext.author_type | string | Yes | Whether the author is a user or a company. LinkedIn only. |
ext.is_repost_quote | boolean | Yes | Whether a reshare added commentary (true) or was a plain repost (false). LinkedIn reposts only. |
ext.article.title | string | No | Title of the shared article. |
ext.article.source | string | No | The article's publisher or domain. |
ext.article.url | string | No | Link to the article. |
ext.article.description | string | No | The link card's summary of the article. |
ext.reaction_type | string | Yes | How the member reacted, as LinkedIn's own rendered sentence (for example 'Bill Gates likes this'), localised. Profile reactions lane only. |
ext.reacted_at | string | Yes | When the member reacted, as an ISO 8601 UTC timestamp; published_at stays the post's own time. Profile reactions lane only. |
ext.reaction | string | Yes | The 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_id | string | Yes | The id of the member's reaction itself on LinkedIn, the activity post.url links. Profile reactions lane only. |
ext.mentioned_accounts | object[] | Yes | The accounts LinkedIn links in the post's text, in order. Our parse of @handles in the caption stays in mentions. |
ext.text_entities | object[] | Yes | The linked ranges of the post's text. |
ext.outbound_links | string[] | Yes | The web links in the post's text, in order, each once. LinkedIn feeds and post search. |
ext.is_edited | boolean | Yes | True when LinkedIn shows the post as edited. LinkedIn feeds and post search. |
ext.comments_disabled | boolean | Yes | True when the author turned comments off on the post. LinkedIn feeds and post search. |
ext.document.title | string | Yes | The document's title. |
ext.document.page_count | number | Yes | How many pages it has. |
ext.document.url | string | Yes | Link to the PDF. |
ext.document.cover_url | string | Yes | Link to the image of its first page. |
ext.poll.question | string | Yes | The question. |
ext.poll.options | object[] | No | The options, in the order LinkedIn shows them. |
ext.poll.total_votes | number | Yes | Votes cast across all options. |
ext.poll.voter_count | number | Yes | How many people voted, where the source reports it. |
ext.poll.is_closed | boolean | Yes | True when the poll has ended. |
ext.poll.remaining | string | Yes | Time left as LinkedIn words it, such as 14h left. |
ext.job.id | string | Yes | The job's id, the one /v1/linkedin/job takes. |
ext.job.title | string | Yes | The job title. |
ext.job.company_name | string | Yes | The hiring company. |
ext.job.company_id | string | Yes | The company's numeric id. |
ext.job.company_url | string | Yes | Link to the company page. |
ext.job.company_logo | string | Yes | Link to the company's logo. |
ext.job.location | string | Yes | Where the job is. |
ext.job.url | string | Yes | Link to the job. |
ext.celebration.headline | string | Yes | The card's headline, such as Starting a New Position. |
ext.celebration.image_url | string | Yes | Link to the card image. |
ext.newsletter.title | string | Yes | The newsletter's name. |
ext.newsletter.url | string | Yes | Link to the newsletter. |
ext.reposted_by.type | string | Yes | user or company where known. |
ext.reposted_by.id | string | Yes | The account's LinkedIn id where known. |
ext.reposted_by.name | string | Yes | Display name. |
ext.reposted_by.username | string | Yes | The member's or page's slug. |
ext.reposted_by.url | string | Yes | Link to the profile or page. |
ext.reposted_at | string | Yes | When the feed's member or page reposted this post, as an ISO 8601 UTC timestamp. LinkedIn feeds. |
ext.author_website | string | Yes | The link on the button in the author's profile header, such as their newsletter or website. LinkedIn feeds and post search. |
ext.author_website_label | string | Yes | The text of that button, for example View my newsletter. LinkedIn feeds and post search. |
ext.aspect_ratio | number | Yes | A video's width divided by its height, so 0.5625 is 9:16. LinkedIn feeds and post search. |
ext.author_is_premium | boolean | Yes | True 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_generated | boolean | Yes | True when the credentials say the image was made with AI. |
ext.content_credentials.issuer | string | Yes | Who issued the signing certificate. |
ext.content_credentials.signer | string | Yes | Who signed the credentials, such as the tool that made the image. |
ext.content_credentials.is_valid | boolean | Yes | True when the credentials verify. |
ext.download_media_urls | object[] | Yes | Permanent links to the downloaded media. Present when the call asked for a download. |
ext.tags | string[] | Yes | Video tags set by the creator. YouTube only. |
ext.categoryId | string | Yes | YouTube's category id, for example 10. |
ext.categoryTitle | string | Yes | Name of the YouTube category. |
ext.topicCategories | string[] | Yes | Wikipedia URLs for the video's topics. YouTube only. |
ext.duration | string | Yes | Video length as an ISO 8601 duration, for example PT3M33S. |
ext.license | string | Yes | Licence the video is published under, for example youtube or creativeCommon. |
ext.madeForKids | boolean | Yes | Whether the video is marked as made for kids. YouTube only. |
ext.defaultAudioLanguage | string | Yes | Language of the video's audio track as a BCP 47 code. |
ext.hasPaidProductPlacement | boolean | Yes | Whether the video discloses a paid product placement. YouTube only. |
ext.caption | string | Yes | Whether the video has captions, as the string true or false. YouTube only. |
ext.playback_availability.visibility | string | Yes | public, unlisted or private, as YouTube reports it. |
ext.playback_availability.age_restricted | boolean | Yes | Whether the video is age-restricted. |
ext.playback_availability.members_only | boolean | Yes | Whether the video is for the channel's paying members only. |
ext.playback_availability.family_safe | boolean | Yes | Whether YouTube marks the video family-safe. |
ext.playback_availability.region_restricted | boolean | Yes | Whether the video is blocked in some countries. |
ext.playback_availability.available_countries | string[] | Yes | The ISO 3166-1 alpha-2 codes of the countries the video plays in, sorted. |
ext.playback_availability.live_content | boolean | Yes | Whether the video is or was a live stream. |
ext.playback_availability.live_now | boolean | Yes | Whether the video is live right now. |
ext.playback_availability.upcoming | boolean | Yes | Whether the video is a scheduled premiere or stream that has not started. |
ext.playback_availability.comments_visible | boolean | Yes | Whether comments are shown on the video. |
ext.playback_availability.ratings_enabled | boolean | Yes | Whether likes are enabled on the video. |
ext.position | number | Yes | Position of the item in the playlist, counting from 0. |
ext.playlistId | string | Yes | Id of the playlist the item belongs to. |
ext.videoOwnerChannelId | string | Yes | Channel id of the video's owner. YouTube playlist items only. |
ext.videoPublishedAt | string | Yes | When the video was published, as an ISO 8601 time. YouTube playlist items only. |
ext.description | string | Yes | Description text from the source record. |
ext.default_language | string | Yes | Default language of the video's metadata as a BCP 47 code. |
ext.localizations | object | Yes | Translated video titles and descriptions, keyed by language code. Present with include_localizations. |
ext.playlist_item_id | string | Yes | Id of the playlist item itself, distinct from the video id in post.id. |
ext.playlist_owner_channel_id | string | Yes | Channel id of the playlist's owner, not necessarily the video's channel. |
ext.playlist_owner_title | string | Yes | Name of the playlist's owner. |
ext.channel_id | string | Yes | The 24 character YouTube channel id (starts with UC). Used because these rows carry no handle. |
ext.published_label | string | Yes | The relative label the source showed instead of a date, for example 'Streamed 3 weeks ago'. |
ext.published_precision | string | Yes | How precise published_at is when the source gave only a relative label: minute, hour, day, week, month or year. |
ext.title_maybe_translated | boolean | Yes | True when the title may be an English machine translation of a non English video title. |
ext.video_count | number | Yes | Number of videos in the playlist. It is not a view count. |
ext.posts_count | number | Yes | /v1/instagram/hashtag only: the exact number of public posts Instagram counts under the hashtag. Live: it moves between calls minutes apart. |
ext.commerce.price | any | No | The item's price: a number on a marketplace listing, an object on a shop product. |
ext.commerce.currency | string | No | ISO 4217 currency code of the price. |
ext.commerce.price_formatted | string | No | Price formatted for display. |
ext.commerce.strikethrough_price_formatted | string | No | The crossed-out previous price, formatted for display. |
ext.commerce.description | string | No | The listing's description. |
ext.commerce.location_text | string | No | Where the item is, as text. |
ext.commerce.latitude | number | No | Latitude of the item in degrees. |
ext.commerce.longitude | number | No | Longitude of the item in degrees. |
ext.commerce.category_id | string | No | The listing category's id. |
ext.commerce.mileage | number | Yes | Mileage, for vehicles. |
ext.commerce.attributes | object[] | No | Listing attributes. |
ext.commerce.delivery_types | string[] | No | How the item can be handed over. |
ext.commerce.availability_text | string | Yes | Availability, as text. |
ext.commerce.listing_date_text | string | No | When the item was listed, as the platform words it. |
ext.commerce.is_sold | boolean | No | True when the item has sold. |
ext.commerce.is_live | boolean | No | True when the listing is live. |
ext.commerce.is_pending | boolean | No | True when a sale is pending. |
ext.commerce.is_hidden | boolean | No | True when the listing is hidden. |
ext.commerce.is_shipping_offered | boolean | No | True when the seller ships the item. |
ext.commerce.is_buy_now_enabled | boolean | No | True when the buyer can buy without messaging first. |
ext.commerce.messaging_enabled | boolean | No | True when buyers can message the seller. |
ext.commerce.seller_id | string | Yes | The seller's id on the platform. |
ext.commerce.seller_name | string | Yes | The seller's name. |
ext.commerce.rating.score | number | No | Average rating. |
ext.commerce.rating.review_count | number | No | How many ratings it is based on. |
ext.commerce.rating.average | number | No | Average rating (same value as score). |
ext.commerce.rating.count | number | No | How many ratings it is based on (same value as review_count). |
ext.commerce.sold.sold_count | number | No | Units sold so far. |
ext.on_screen_texts | string[] | Yes | Text the creator typed onto the video with TikTok's text tool. |
ext.topic_tag | string | Yes | Name of the topic a Threads post is filed under. Not a slug, so join on topic_tag_id. |
ext.reshare_count | number | Yes | The boosted reshare figure Threads shows in the app. |
ext.dsp_ids | object | Yes | The same track's ids on music stores, keyed by lowercase store name. |
ext.topic_tag_id | string | Yes | Id of the Threads topic. Use it to join, not the topic name. |
ext.amazon_shop_lists | object[] | Yes | The creator's curated idea lists. |
ext.amazon_shop_trending_picks | object[] | Yes | Products the creator features as trending picks. |
ext.amazon_shop_curations | object[] | Yes | Shoppable post sets the creator curated. |
ext.amazon_shop_socials | string[] | Yes | The creator's profile URLs outside Amazon. Amazon Influencer Shop only. |
ext.ad.page_id | string | No | Id of the advertiser's page. |
ext.ad.page_profile_uri | string | No | Link to the advertiser's page. |
ext.ad.page_like_count | number | No | Followers or likes of the advertiser's page. |
ext.ad.page_categories | string[] | No | The advertiser page's categories. |
ext.ad.brand_name | string | No | The advertiser's name. |
ext.ad.currency | string | No | ISO 4217 currency code of the spend figures. |
ext.ad.spend | any | No | Spend range the library reports. The shape differs by library and is null when it hides spend. |
ext.ad.spent | string | No | Spend as the library words it. Empty when not disclosed. |
ext.ad.reach_estimate | any | No | Reach estimate the library reports. The shape differs by library and is null when it hides reach. |
ext.ad.estimated_audience | string | No | Audience size band, such as 10K-100K. |
ext.ad.publisher_platforms | string[] | No | Where the ad ran. |
ext.ad.categories | string[] | No | The ad's content categories. |
ext.ad.targeted_or_reached_countries | string[] | No | Countries the ad targeted or reached. |
ext.ad.country_code | any | No | The country or countries the ad ran in. |
ext.ad.cta_text | string | No | The call-to-action button text. |
ext.ad.cta_type | string | No | The call-to-action type, such as LEARN_MORE. |
ext.ad.link_url | string | No | Where the ad sends people. |
ext.ad.landing_page | string | No | Landing page the ad opens. |
ext.ad.landing_page_url | string | Yes | Landing page the ad opens. |
ext.ad.profile_web_link | string | No | Link to the advertiser's profile. |
ext.ad.is_active | boolean | No | True when the ad is still running. |
ext.ad.end_date_iso | string | No | When the ad stopped, ISO 8601. |
ext.ad.last_shown_date | number | No | When the ad was last shown, Unix milliseconds. |
ext.ad.display_format | string | No | The ad's display format, such as DCO. |
ext.ad.ad_format | string | Yes | The ad's format. |
ext.ad.title | string | No | The ad's headline. |
ext.ad.caption | string | No | The ad's caption. |
ext.ad.video_hd_url | string | Yes | Link to the high-definition video. |
ext.ad.video_sd_url | string | Yes | Link to the standard-definition video. |
ext.ad.video_url_540p | string | No | Link to the 540p video. |
ext.ad.video_url_360p | string | No | Link to the 360p video. |
ext.ad.video_id | string | No | The video's id. |
ext.ad.image_urls | string[] | No | Links to the ad's images. |
ext.ad.audit_status | string | No | The library's review status code for the ad. |
ext.ad.type | string | No | The library's ad type code. |
ext.ad.source | string | No | The library the ad came from. |
ext.ad.objectives | object[] | No | The campaign objectives the advertiser chose. |
ext.ad.objective | string | No | The campaign objective's code. |
ext.ad.industry | string | No | The industry the ad belongs to. |
ext.ad.language | string | Yes | The ad's language. |
ext.ad.ctr | number | No | Click-through rate band, 0 to 1. |
ext.ad.cost_score | number | No | Relative cost score. |
ext.ad.rank | number | No | The ad's rank on the board it was read from. |
ext.ad.like_tier | string | Yes | Like-count tier. |
ext.ad.is_spark_ad | boolean | Yes | True when the ad boosts an organic post. |
ext.ad.period_days | number | No | Length of the ranking window in days. |
ext.apple_music.kind | string | No | What the item is, such as album or songs. |
ext.apple_music.track_count | number | No | How many tracks an album has. |
ext.apple_music.release_info | string | No | Release date, track count, duration and copyright as one text block. |
ext.apple_music.artist_url | string | No | Link to the artist's page. |
ext.apple_music.artist_id | string | No | The artist's id. |
ext.apple_music.release_date | string | No | Release date, as YYYY-MM-DD. |
ext.apple_music.genres | object[] | No | Genres the item belongs to. |
ext.apple_music.content_advisory | string | Yes | Content advisory label, such as explicit. |
ext.apple_music.track_number | number | No | Position of the track on its album. |
ext.apple_music.explicit | boolean | No | True when the track is marked explicit. |
ext.feedback_id | string | Yes | Join key that /v1/facebook/post/comments takes to read the post's comments. |
ext.question_id | string | Yes | Naver 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_no | number | Yes | Naver KnowledgeiN only: which answer of the question this row is (Naver's answerNo), read from the row's link. |
ext.answer_nos | number[] | Yes | Naver KnowledgeiN with group=question only: every answer number of the question that was on the page, best-ranked first. |
ext.published_at_est | string | Yes | Naver 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_basis | string | Yes | How 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.description | string | No | The event's description. |
ext.event.start_timestamp | number | No | When the event starts, in Unix seconds. |
ext.event.end_timestamp | number | Yes | When the event ends, in Unix seconds. |
ext.event.time_text | string | No | The event time as the platform words it, with time zone. |
ext.event.duration_text | string | No | How long the event lasts, as text. |
ext.event.location_name | string | No | Name of the venue, or Online event. |
ext.event.address | string | Yes | Street address. |
ext.event.city | string | Yes | City. |
ext.event.latitude | number | Yes | Latitude of the venue in degrees. |
ext.event.longitude | number | Yes | Longitude of the venue in degrees. |
ext.event.hosts | object[] | No | The people or pages hosting the event. |
ext.event.host_context_text | string | No | The host line, such as Event by .... |
ext.event.category | string | No | The event's category. |
ext.event.is_online | boolean | No | True when the event is online. |
ext.event.is_canceled | boolean | No | True when the event is cancelled. |
ext.event.is_past | boolean | No | True when the event has already happened. |
ext.event.privacy | string | No | Who can see the event, such as public. |
ext.event.ticket_url | string | Yes | Link to buy tickets. |
ext.event.attendance_count | number | No | Total attendance figure. |
ext.event.interested_count | number | No | People who marked themselves interested. |
ext.event.going_count | number | No | People who said they are going. |
ext.event.id | string | Yes | The event's LinkedIn id. |
ext.event.name | string | Yes | The event's name. |
ext.event.date_text | string | Yes | When the event runs, as LinkedIn words it, with time zone. |
ext.event.location | string | Yes | Where the event is, or Online. |
ext.event.url | string | Yes | Link to the event. |
ext.event.banner_url | string | Yes | Link to the event's banner image. |
ext.trend.rank | number | No | The row's rank on the board. |
ext.trend.country_code | string | No | The market the board covers, as a country code. |
ext.trend.chart | string | No | Which chart the row ranks on, such as songs. |
ext.trend.chart_title | string | No | The chart's title in the board's language. |
ext.trend.updated_at | string | No | When the board was last refreshed, ISO 8601. |
ext.trend.period_days | number | No | Length of the ranking window in days. |
ext.trend.posts | number | No | How many posts used the item in the window. |
ext.trend.views | number | No | Views the item earned in the window. |
ext.trend.period_views | number | No | Views in the window. |
ext.trend.organic_views | number | No | Organic views in the window. |
ext.trend.six_second_view_through_rate | number | No | Share of views that reached six seconds, 0 to 1. |
ext.trend.engagement_rate | number | No | Engagement rate for the window, 0 to 1. |
ext.trend.order_by | string | No | The sort the board was read with. |
ext.trend.industry | string | Yes | The industry code the board covers. |
ext.trend.industry_id | string | Yes | The industry's id. |
ext.trend.industry_label | string | Yes | The industry's name. |
ext.trend.boards | object[] | No | Every board the row ranks on, with its rank there. |
ext.trend.popularity_curve | object[] | No | Daily popularity values for the window. |
ext.trend.top_creators | object[] | No | Creators who used the item most in the window. |
ext.trend.content_tags | string[] | No | Tags describing the video's content. |
ext.updated_at | string | Yes | When the platform last changed the post, as opposed to when it was published. |
ext.alt_text | string | Yes | Pinterest's machine caption of the image. Never the creator's own text. |
ext.board_name | string | Yes | Name of the board the pin was saved to. Pinterest only. |
ext.topic_labels | string[] | Yes | |
ext.story_expires_at | string | Yes | |
ext.numeric_id | number | Yes | GitHub's numeric REST id, beside the GraphQL node id in post.id. |
ext.outbound_url | string | Yes | The page a Pinterest pin saves. Absent when it saves none. |
ext.search_result_id | string | Yes | The 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.id | string | No | The group's key, as its link spells it (the numeric id or the vanity name). |
ext.group.url | string | No | Canonical link to the group. |
ext.group.name | string | Yes | The group's name. |
ext.group.members | number | Yes | The 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.
| Platform | author.verified | engagement.saves | content.duration_seconds | engagement.shares | engagement.views | author.avatar_url | content.media_urls | url | engagement.comments | content.thumbnail_url | flags.pinned | engagement.likes |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Amazon | yes | yes | yes | |||||||||
| Apple Music | yes | yes | yes | yes | ||||||||
| Bluesky | yes | yes | yes | yes | ||||||||
| Douyin | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | |
| yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | ||
| Gab | yes | yes | yes | yes | yes | yes | ||||||
| GitHub | yes | yes | yes | yes | yes | yes | ||||||
| yes | yes | yes | yes | |||||||||
| Hacker News | yes | yes | yes | |||||||||
| yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | ||
| Kick | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | ||
| Kwai | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | |
| yes | yes | yes | yes | yes | yes | yes | yes | yes | ||||
| Naver | yes | yes | yes | yes | yes | yes | yes | |||||
| yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | ||
| Product Hunt | yes | yes | yes | yes | ||||||||
| Quora | yes | yes | yes | yes | yes | |||||||
| yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | |
| Rumble | yes | yes | yes | yes | yes | |||||||
| Spotify | yes | yes | yes | yes | yes | |||||||
| Telegram | 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 |
| Truth Social | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | ||
| Twitch | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | ||
| Twitter/X | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | ||
| yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | ||
| Xiaohongshu | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | ||
| YouTube | yes | yes | yes | yes | yes | yes | yes | yes |
Machine-readable schema
Validate responses programmatically against the JSON Schema (2020-12):
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.
Unified schema
One Post shape, one Author shape, one Comment shape, the same across every SocialCrawl platform. Field-level guarantees, per-platform availability, and machine-readable JSON Schema.
Author schema
The unified SocialCrawl author or creator profile schema. Every field, its type, per-platform availability, and a machine-readable JSON Schema, generated from the canonical Zod source.
