SocialCrawl
Unified schema

Comment schema

The unified SocialCrawl comment 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 comment gives you this exact shape, whatever the source platform. Write your parser once and the same code reads comment data from every platform below. That is the unified schema: one contract instead of a dozen raw upstream formats.

Field reference

FieldTypeNullableDescription
idstringNoPlatform-specific comment ID (always a string)
urlstringYesDirect URL to the comment on the source platform
parent_idstringYesParent comment ID for nested replies, or null for top-level comments
post_idstringYesID of the post this comment belongs to
textstringYesComment body. Tombstone sentinels ([deleted] / [removed]) are collapsed to null upstream: customers never see them.
author.usernamestringYesComment author username (null when tombstoned)
author.display_namestringYesComment author display name
author.avatar_urlstringYesURL to comment author profile picture
author.verifiedbooleanYesWhether the comment author is verified
engagement.likesnumberYesLike / upvote count
engagement.repliesnumberYesReply / child-comment count. 0 when the upstream structurally reports the count and the comment has no replies; null only when the upstream does not surface a reply count at all.
flags.pinnedbooleanYesPinned flag (null when platform does not surface)
flags.deletedbooleanNoWhether the comment is tombstoned (always present, even when false)
flags.liked_by_creatorbooleanYes/v1/instagram/post/comments only: true when the post's creator liked (hearted) the comment, false when not, null when the source that served the call could not tell. Absent on every other endpoint.
published_atstring or numberYesComment 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 comment.ext.published_at_epoch for one deprecation cycle.
repliesany[]YesNested reply tree: array of child comments, each itself a full Comment object with its own replies. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via parent_id.

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.replies_tokenstringYesYouTube reply continuation token: pass to /v1/youtube/video/comment/replies?continuationToken=
ext.replies_cursorstringYesReddit reply-branch continuation cursor. Present when this comment's reply tree is truncated upstream: pass it back as ?cursor= on /v1/reddit/post/comments to load the rest of the branch.
ext.depthnumberYesReddit comment nesting depth as the source reports it: 0 on a top-level comment, 1 on a direct reply, and so on. Present when the thread arrived flat and was re-nested into replies[], so you can verify that nesting independently.
ext.published_at_epochnumberYesRaw Unix epoch for published_at (present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 string).
ext.feedback_idstringYesFacebook comment feedback id: feeds /v1/facebook/post/comment/replies
ext.expansion_tokenstringYesFacebook comment expansion/paginator token: feeds /v1/facebook/post/comment/replies
ext.author_idstringYesThe commenter's platform-native numeric user id, where the upstream exposes one.
ext.ip_locationstringYesProvince the commenter posted from. Xiaohongshu only, not a profile location.
ext.urnstringYesLinkedIn member urn of the commenter.
ext.reaction_countsobject[]YesReaction counts by type.
ext.is_editedbooleanYesWhether the comment was edited.
ext.previous_replies_tokenstringYesCursor to load the earlier replies of a LinkedIn comment thread.
ext.author_headlinestringYesThe commenter's profile headline. LinkedIn only.
ext.author_typestringYesWhether the commenter is a member (user) or a page (company). LinkedIn only.
ext.author_urnstringYesThe commenter's LinkedIn member URN (ACoAA...), the id the profile lookups take; null for a page. LinkedIn only.
ext.is_contributionbooleanYesWhether the comment is a contribution to a LinkedIn collaborative article. LinkedIn only.
ext.has_previous_repliesbooleanYesWhether the thread has more replies than comment.replies carries. LinkedIn only.
ext.updated_atstringYesWhen the comment was last edited, as an ISO 8601 time. YouTube only.
ext.author_channel_idstringYesThe commenter's YouTube channel id.
ext.author_urlstringYesURL of the commenter's channel page.
ext.viewer_ratingstringYesWhether the requesting viewer liked the comment: like or none. YouTube only.
ext.text_originalstringYesThe comment body without HTML escaping. YouTube only.
ext.preview_repliesobject[]YesThe first few replies, inline, as the source sends them.
ext.lookup.found_viastringNoHow the comment was found, such as id_scan.
ext.lookup.pages_fetchednumberNoHow many pages of comments were read.
ext.lookup.comments_scannednumberNoHow many comments were read.
ext.lookup.sort_basisstringNoThe sort order the scan used.
ext.lookup.position_hintstringNoA cursor that resumes the scan at this comment.
ext.lookup.post_comment_countnumberNoThe post's total comment count.
ext.post_titlestringYesTitle of the parent post, so a comment found by search can be read in context.
ext.post_urlstringYesURL of the parent post.
ext.subredditstringYesName of the subreddit the comment was made in.
ext.subreddit_subscribersnumberYesSubscriber count of that subreddit.
ext.post_scorenumberYesScore of the parent post.
ext.post_comment_countnumberYesNumber of comments on the parent post.
ext.post_authorstringYesUsername of the author of the parent post.
ext.post_published_atstringYesWhen the parent post was published.
ext.post_flairstringYesLink flair of the parent post.
ext.is_submitterbooleanYesWhether the commenter also wrote the post they are replying under. Reddit's OP badge.
ext.edited_atstringYesWhen the comment was last edited, as an ISO 8601 UTC time. Null if it never was.
ext.removed_bystringYes
ext.controversialitynumberYesReddit's controversiality flag, 1 when up and down votes are roughly balanced and 0 otherwise.
ext.content_languagestringYesISO 639-1 language tag for this comment, when the source reports one. X writes zxx / und for no linguistic content; those collapse to null.
ext.author_followersnumberYesThe commenter's follower count as embedded in this row. Snapshot as of whenever the replies source saw the account, not a live figure. On X this is present on every tweet/replies row.
ext.author_followingnumberYesThe commenter's following count as embedded in this row. Same snapshot caveat as author_followers.
ext.author_posts_countnumberYesThe commenter's post count as embedded in this row. Same snapshot caveat as author_followers.
ext.author_locationstringYesLocation the commenter set on their profile, as free text. X only.
ext.quote_countnumberYesHow many quote-posts this comment has, when the source reports it. On X a reply is a tweet, so this is the same figure post.ext.quote_count carries on tweet lanes.
ext.viewsnumberYesView count for this comment, when the source reports it. On X a reply is a tweet and the count is public on posts from ~2022 onward.
ext.savesnumberYesBookmark / save count for this comment, when the source reports it. On X this is legacy.bookmark_count.

Platform availability

19 platforms return the Comment 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.

Platformparent_idauthor.verifiedflags.pinnedurlpost_idauthor.usernameengagement.repliesauthor.avatar_urlauthor.display_nameengagement.likes
Douyinyesyesyesyesyesyesyesyes
Facebookyesyesyesyesyes
Gabyesyesyesyesyesyesyes
GitHubyesyesyesyesyes
Goodreadsyesyesyes
Googleyesyesyesyesyesyesyes
Hacker Newsyesyesyesyes
Instagramyesyesyesyesyesyesyesyesyesyes
LinkedInyesyesyes
Product Huntyesyesyesyesyesyesyesyesyes
Reddityesyesyesyesyesyesyesyesyes
Rumbleyesyesyesyesyes
Snapchatyesyesyesyes
Threadsyesyesyesyesyesyesyes
TikTokyesyesyesyesyesyesyesyesyesyes
Twitter/Xyesyesyesyesyesyesyesyes
Weiboyesyesyesyesyesyesyes
Xiaohongshuyesyesyesyesyesyesyesyes
YouTubeyesyesyesyesyes

Machine-readable schema

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

/schemas/comment.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 Comment / CommentList archetype return this shape:

Douyin · Facebook · Gab · GitHub · Goodreads · Google · Hacker News · Instagram · LinkedIn · Prism · Product Hunt · Reddit · Rumble · Snapchat · Threads · TikTok · 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