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.
Comment schema
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
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | No | Platform-specific comment ID (always a string) |
url | string | Yes | Direct URL to the comment on the source platform |
parent_id | string | Yes | Parent comment ID for nested replies, or null for top-level comments |
post_id | string | Yes | ID of the post this comment belongs to |
text | string | Yes | Comment body. Tombstone sentinels ([deleted] / [removed]) are collapsed to null upstream — customers never see them. |
author.username | string | Yes | Comment author username (null when tombstoned) |
author.display_name | string | Yes | Comment author display name |
author.avatar_url | string | Yes | URL to comment author profile picture |
author.verified | boolean | Yes | Whether the comment author is verified |
engagement.likes | integer | Yes | Like / upvote count |
engagement.replies | integer | Yes | Reply / 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.pinned | boolean | Yes | Pinned flag (null when platform does not surface) |
flags.deleted | boolean | No | Whether the comment is tombstoned (always present, even when false) |
published_at | string or integer | Yes | Comment 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. |
replies | object[] | Yes | Nested 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.
| Field | Type | Nullable | Description |
|---|---|---|---|
ext.replies_token | string | Yes | YouTube reply continuation token — pass to /v1/youtube/video/comment/replies?continuationToken= |
ext.replies_cursor | string | Yes | Reddit 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.published_at_epoch | integer | Yes | Raw Unix epoch for published_at (present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 string). |
ext.feedback_id | string | Yes | Facebook comment feedback id — feeds /v1/facebook/post/comment/replies |
ext.expansion_token | string | Yes | Facebook comment expansion/paginator token — feeds /v1/facebook/post/comment/replies |
ext.urn | string | Yes | |
ext.reaction_counts | string[] | Yes | |
ext.is_edited | boolean | Yes | |
ext.previous_replies_token | string | Yes | |
ext.updated_at | string | Yes | |
ext.author_channel_id | string | Yes | |
ext.author_url | string | Yes | |
ext.viewer_rating | string | Yes | |
ext.text_original | string | Yes | |
ext.preview_replies | string[] | Yes |
Platform availability
10 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.
| Platform | parent_id | post_id | author.display_name | flags.pinned | author.avatar_url | author.verified | engagement.likes | engagement.replies | url | author.username |
|---|---|---|---|---|---|---|---|---|---|---|
| yes | yes | yes | yes | yes | ||||||
| GitHub | yes | 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 | yes | yes | yes | yes | yes | yes | yes | yes | yes | |
| Rumble | yes | yes | yes | yes | yes | |||||
| TikTok | yes | yes | yes | yes | yes | yes | yes | yes | ||
| YouTube | 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 Comment / CommentList archetype return this shape:
Facebook · GitHub · Google · Hacker News · Instagram · LinkedIn · Reddit · Rumble · TikTok · TikTok Shop · YouTube
See how the same fields map to each platform's raw upstream names in the cross-platform field equivalence table.