Post API for Facebook, Instagram, Rumble, TikTok and YouTube: the post schema

Endpoints

10 endpoints return posts on Facebook, Instagram, Rumble, TikTok and YouTube.

Schema

Single-item endpoints return this object as data; list endpoints return an array of them as data with a page object. The standard meta comes with every response.

Field	Type	Description
`platform`	`string`	Platform ID (tiktok, youtube, …).
`id`	`string`	Platform-native post ID (string; Instagram shortcode, Reddit without t3_).
`url`	`string` (uri)	Canonical post URL.
`type`	`string`	Normalized content shape. New values may be added; treat unknown values as other. One of `video`, `image`, `carousel`, `text`, `link`, `audio`
`platform_type`	`string` or `null`	The platform's own product label, lowercase (reel, short, story, live, tweet, …).
`title`	`string` or `null`	Headline (YouTube title, Reddit title); null on caption-only platforms.
`text`	`string` or `null`	Caption, description or body as plain text.
`language`	`string` or `null`	BCP-47 language of text, when the platform states it.
`published_at`	`string` (date-time) or `null`	When the post went public, RFC 3339 UTC.
`author`	`object`	The posting account.
`author.id`	`string` or `null`	Platform-native account ID; null when only the handle is known.
`author.username`	`string` or `null`	Handle without the @; null when the account has none.
`author.display_name`	`string` or `null`	Display name shown on the profile.
`author.url`	`string` (uri) or `null`	Canonical profile URL.
`author.avatar_url`	`string` (uri) or `null`	Profile picture URL. Platform CDN URLs can expire within hours.
`author.is_verified`	`boolean` or `null`	Platform verification badge; null where the platform has no badge.
`coauthors`	`object[]`	Other accounts credited as co-authors of the post (Instagram and Facebook collabs, YouTube collaborations), in the platform's order, author excluded; [] if none.
`coauthors[].id`	`string` or `null`	Platform-native account ID; null when only the handle is known.
`coauthors[].username`	`string` or `null`	Handle without the @; null when the account has none.
`coauthors[].display_name`	`string` or `null`	Display name shown on the profile.
`coauthors[].url`	`string` (uri) or `null`	Canonical profile URL.
`coauthors[].avatar_url`	`string` (uri) or `null`	Profile picture URL. Platform CDN URLs can expire within hours.
`coauthors[].is_verified`	`boolean` or `null`	Platform verification badge; null where the platform has no badge.
`duration_ms`	`integer` or `null`	Length of the primary video or audio in milliseconds; null for other posts.
`thumbnail_url`	`string` (uri) or `null`	Cover or poster image URL.
`media`	`object[]`	Attachments in display order (carousel items); [] for text posts.
`media[].type`	`string`	Kind of file. New values may be added; treat unknown values as other. One of `image`, `video`, `audio`, `gif`
`media[].url`	`string` (uri) or `null`	Direct file URL; null when the platform withholds it, or when the link would only work from SocialTap's network or with a login. Often signed and expiring: see expires_at.
`media[].expires_at`	`string` (date-time) or `null`	When url stops working, RFC 3339 UTC, read from the platform's signed URL; null when unknown or when it does not expire.
`media[].thumbnail_url`	`string` (uri) or `null`	Poster or preview image URL.
`media[].width`	`integer` or `null`	Width in pixels.
`media[].height`	`integer` or `null`	Height in pixels.
`media[].duration_ms`	`integer` or `null`	Duration in milliseconds (video and audio only).
`media[].alt_text`	`string` or `null`	Accessibility text provided by the author or platform.
`hashtags`	`string[]`	Hashtags without #, case kept; [] if none.
`mentions`	`string[]`	Mentioned or tagged usernames without @; [] if none.
`is_pinned`	`boolean` or `null`	Pinned to the author's profile.
`is_sponsored`	`boolean` or `null`	Labeled as a paid partnership or branded content.
`is_nsfw`	`boolean` or `null`	Marked adult or sensitive by the platform.
`metrics`	`object`	Counts at fetch time; null = hidden or not exposed, 0 = zero.
`metrics.view_count`	`integer` or `null`	Views or plays.
`metrics.like_count`	`integer` or `null`	Likes, hearts, total reactions or upvotes; never negative. Null when hidden by the owner.
`metrics.comment_count`	`integer` or `null`	Comments and replies.
`metrics.share_count`	`integer` or `null`	Shares or sends (not reposts).
`metrics.repost_count`	`integer` or `null`	Reposts, retweets or reshares.
`metrics.quote_count`	`integer` or `null`	Quote posts.
`metrics.save_count`	`integer` or `null`	Saves, bookmarks or favorites.
`platform_specific`	`object`	Fields only this platform has, under its ID (platform_specific.<platform>); each null when unknown.
`platform_specific.tiktok`	`object` or `null`	A TikTok post's own fields.
`platform_specific.tiktok.author_sec_uid`	`string` or `null`	The author's secUid, TikTok's account key that survives a rename.
`platform_specific.tiktok.country_code`	`string` or `null`	ISO 3166-1 alpha-2 country TikTok registers the post to (not the viewer's).
`platform_specific.tiktok.is_ad`	`boolean` or `null`	The post runs as a TikTok ad.
`platform_specific.tiktok.is_ai_generated`	`boolean` or `null`	TikTok labels the post AI-generated.
`platform_specific.tiktok.location`	`object` or `null`	The tagged place; null when none.
`platform_specific.tiktok.location.id`	`string` or `null`	Place ID.
`platform_specific.tiktok.location.name`	`string` or `null`	Place name.
`platform_specific.tiktok.location.address`	`string` or `null`	Address line.
`platform_specific.tiktok.location.city`	`string` or `null`	City.
`platform_specific.tiktok.location.category`	`string` or `null`	Top-level place category.
`platform_specific.tiktok.music`	`object` or `null`	The post's sound.
`platform_specific.tiktok.music.id`	`string` or `null`	Sound ID.
`platform_specific.tiktok.music.title`	`string` or `null`	Sound title.
`platform_specific.tiktok.music.author_name`	`string` or `null`	Who TikTok credits for the sound.
`platform_specific.tiktok.music.is_original`	`boolean` or `null`	An original sound a creator uploaded (false: a catalogue track).
`platform_specific.tiktok.music.duration_ms`	`integer` or `null`	Sound length in milliseconds.
`platform_specific.tiktok.music.cover_url`	`string` (uri) or `null`	Sound cover image URL.
`platform_specific.tiktok.music.play_url`	`string` (uri) or `null`	Audio file URL, signed and expiring.
`platform_specific.youtube`	`object` or `null`	A YouTube video's own fields.
`platform_specific.youtube.category`	`string` or `null`	YouTube category (Music, Gaming, …), in English.
`platform_specific.youtube.keywords`	`string[]`	The uploader's tags; [] when none.
`platform_specific.youtube.chapters`	`object[]`	Chapters in playback order; [] when none.
`platform_specific.youtube.chapters[].title`	`string` or `null`	Chapter title.
`platform_specific.youtube.chapters[].start_ms`	`integer` or `null`	Start, in ms from the beginning.
`platform_specific.youtube.description_links`	`string[]`	Links in the description, in order, deduplicated; [] when none.
`platform_specific.youtube.is_unlisted`	`boolean` or `null`	Unlisted: watchable by link, not listed on the channel or in search.
`platform_specific.youtube.is_age_restricted`	`boolean` or `null`	Viewers must sign in to confirm their age; null when the answer does not tell.
`platform_specific.youtube.is_paywalled`	`boolean` or `null`	Must be bought or rented (movies, paid content).
`platform_specific.youtube.is_live_now`	`boolean` or `null`	A live stream on air now.
`platform_specific.youtube.live_started_at`	`string` (date-time) or `null`	When a live stream or premiere went on air; null if never live.
`platform_specific.youtube.live_ended_at`	`string` (date-time) or `null`	When a live stream or premiere ended; null while live or if never live.
`platform_specific.youtube.scheduled_start_at`	`string` (date-time) or `null`	When a scheduled stream or premiere is due to start; null otherwise.
`platform_specific.youtube.author_subscriber_count`	`integer` or `null`	The channel's subscriber count, rounded by YouTube (in approximate_fields); null when hidden.
`platform_specific.rumble`	`object` or `null`	A Rumble video's own fields.
`platform_specific.rumble.embed_id`	`string` or `null`	The video's embed player ID (rumble.com/embed/<embed_id>/): its own namespace, not id.
`platform_specific.rumble.embed_url`	`string` (uri) or `null`	The embeddable player URL.
`platform_specific.rumble.numeric_id`	`string` or `null`	Rumble's numeric video ID, which its own services use.
`platform_specific.rumble.dislike_count`	`integer` or `null`	Thumbs-down votes. Exact in Rumble's JSON (shorts, grid lists); a video's page and the older HTML cards cut it to three significant digits from 1,000 (in approximate_fields).
`platform_specific.rumble.category`	`string` or `null`	Rumble's primary category (News, Podcasts, …).
`platform_specific.rumble.secondary_category`	`string` or `null`	Rumble's secondary category; null when none.
`platform_specific.rumble.keywords`	`string[]`	The uploader's tags; [] when none.
`platform_specific.rumble.caption_tracks`	`object[]`	Caption tracks (WebVTT); [] when none.
`platform_specific.rumble.caption_tracks[].language`	`string` or `null`	Language code (en, es, …).
`platform_specific.rumble.caption_tracks[].label`	`string` or `null`	Rumble's label ("English (auto)").
`platform_specific.rumble.caption_tracks[].url`	`string` (uri) or `null`	WebVTT file URL.
`platform_specific.rumble.caption_tracks[].is_auto_generated`	`boolean` or `null`	Generated by Rumble's speech recognition.
`platform_specific.rumble.files`	`object[]`	Every file and stream Rumble's player offers, largest video first; [] when none.
`platform_specific.rumble.files[].kind`	`string` or `null`	video (picture and sound), audio (sound only) or preview (the seek bar's low-resolution video, no sound). New values may be added. One of `video`, `audio`, `preview`
`platform_specific.rumble.files[].format`	`string` or `null`	mp4 or webm file, hls playlist (all qualities), tar (one HLS quality packed in one file; url is its playlist) or aac audio. New values may be added. One of `mp4`, `webm`, `hls`, `tar`, `aac`
`platform_specific.rumble.files[].url`	`string` (uri) or `null`	File or playlist URL.
`platform_specific.rumble.files[].width`	`integer` or `null`	Width in pixels; null for audio and playlists.
`platform_specific.rumble.files[].height`	`integer` or `null`	Height in pixels; null for audio and playlists.
`platform_specific.rumble.files[].bitrate_kbps`	`integer` or `null`	Bitrate in kbit/s.
`platform_specific.rumble.files[].size_bytes`	`integer` or `null`	File size in bytes; null when Rumble does not state it.
`platform_specific.rumble.is_live_now`	`boolean` or `null`	A live stream on air now.
`platform_specific.rumble.live_started_at`	`string` (date-time) or `null`	When a live stream went on air; null if never live.
`platform_specific.rumble.scheduled_start_at`	`string` (date-time) or `null`	When a scheduled live stream is due to start; null otherwise.
`platform_specific.rumble.concurrent_viewer_count`	`integer` or `null`	Viewers watching a live stream now; null when not live.
`platform_specific.rumble.is_age_restricted`	`boolean` or `null`	Viewers must confirm their age to watch; null when the source does not show it.
`platform_specific.rumble.author_follower_count`	`integer` or `null`	The channel's or user's follower count. Exact in Rumble's JSON (shorts, lists); a video's page cuts it to three significant digits (in approximate_fields).
`platform_specific.instagram`	`object` or `null`	An Instagram post's own fields (core/post_instagram.go).
`platform_specific.instagram.is_ai_generated`	`boolean` or `null`	Instagram shows its AI label (made or edited with AI); false when it shows none.
`platform_specific.facebook`	`object` or `null`	A Facebook post's own fields.
`platform_specific.facebook.feedback_id`	`string` or `null`	Facebook's feedback ID of the post: the thread its comments and reactions hang on.
`platform_specific.facebook.video_id`	`string` or `null`	The video's ID (facebook.com/reel/<video_id>) on a video or reel post; null on other posts.
`platform_specific.facebook.reactions`	`object[]`	Reactions by type, most first, as Facebook lists them under the post; [] when none.
`platform_specific.facebook.reactions[].type`	`string`	Reaction type. New values may be added. One of `like`, `love`, `care`, `haha`, `wow`, `sad`, `angry`
`platform_specific.facebook.reactions[].count`	`integer` or `null`	How many people reacted with it.
`platform_specific.facebook.shared_post`	`object` or `null`	The post this one reshares; null when it is not a reshare.
`platform_specific.facebook.shared_post.id`	`string` or `null`	Its post ID.
`platform_specific.facebook.shared_post.url`	`string` (uri) or `null`	Its URL.
`platform_specific.facebook.shared_post.author`	`object`	Its author.
`platform_specific.facebook.shared_post.author.id`	`string` or `null`	Platform-native account ID; null when only the handle is known.
`platform_specific.facebook.shared_post.author.username`	`string` or `null`	Handle without the @; null when the account has none.
`platform_specific.facebook.shared_post.author.display_name`	`string` or `null`	Display name shown on the profile.
`platform_specific.facebook.shared_post.author.url`	`string` (uri) or `null`	Canonical profile URL.
`platform_specific.facebook.shared_post.author.avatar_url`	`string` (uri) or `null`	Profile picture URL. Platform CDN URLs can expire within hours.
`platform_specific.facebook.shared_post.author.is_verified`	`boolean` or `null`	Platform verification badge; null where the platform has no badge.
`platform_specific.facebook.link`	`object` or `null`	The link card a post shares (an article, a site); null when none.
`platform_specific.facebook.link.url`	`string` (uri) or `null`	The linked page, as the author shared it (Facebook's l.facebook.com redirect removed).
`platform_specific.facebook.link.title`	`string` or `null`	The card's headline.
`platform_specific.facebook.link.image_url`	`string` (uri) or `null`	The card's image.
`approximate_fields`	`string[]`	JSON paths of values rounded by the platform or parsed from display text. A list path (external_links) means the list may be incomplete. [] when all exact.
`unknown_fields`	`string[]`	JSON paths of lists whose [] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. [] when every list is known.

platformstring

Platform ID (tiktok, youtube, …).

idstring

Platform-native post ID (string; Instagram shortcode, Reddit without t3_).

urlstring uri

Canonical post URL.

typestring

Normalized content shape. New values may be added; treat unknown values as other.

One ofvideoimagecarouseltextlinkaudio

platform_typestringnullable

The platform's own product label, lowercase (reel, short, story, live, tweet, …).

titlestringnullable

Headline (YouTube title, Reddit title); null on caption-only platforms.

textstringnullable

Caption, description or body as plain text.

languagestringnullable

BCP-47 language of text, when the platform states it.

published_atstring date-timenullable

When the post went public, RFC 3339 UTC.

authorobject

The posting account.

Show 6 child fields

idstringnullable

Platform-native account ID; null when only the handle is known.

usernamestringnullable

Handle without the @; null when the account has none.

display_namestringnullable

Display name shown on the profile.

urlstring urinullable

Canonical profile URL.

avatar_urlstring urinullable

Profile picture URL. Platform CDN URLs can expire within hours.

is_verifiedbooleannullable

Platform verification badge; null where the platform has no badge.

coauthorsobject[]

Other accounts credited as co-authors of the post (Instagram and Facebook collabs, YouTube collaborations), in the platform's order, author excluded; [] if none.

Show 6 child fields

idstringnullable

Platform-native account ID; null when only the handle is known.

usernamestringnullable

Handle without the @; null when the account has none.

display_namestringnullable

Display name shown on the profile.

urlstring urinullable

Canonical profile URL.

avatar_urlstring urinullable

Profile picture URL. Platform CDN URLs can expire within hours.

is_verifiedbooleannullable

Platform verification badge; null where the platform has no badge.

duration_msintegernullable

Length of the primary video or audio in milliseconds; null for other posts.

thumbnail_urlstring urinullable

Cover or poster image URL.

mediaobject[]

Attachments in display order (carousel items); [] for text posts.

Show 8 child fields

typestring

Kind of file. New values may be added; treat unknown values as other.

One ofimagevideoaudiogif

urlstring urinullable

Direct file URL; null when the platform withholds it, or when the link would only work from SocialTap's network or with a login. Often signed and expiring: see expires_at.

expires_atstring date-timenullable

When url stops working, RFC 3339 UTC, read from the platform's signed URL; null when unknown or when it does not expire.

thumbnail_urlstring urinullable

Poster or preview image URL.

widthintegernullable

Width in pixels.

heightintegernullable

Height in pixels.

duration_msintegernullable

Duration in milliseconds (video and audio only).

alt_textstringnullable

Accessibility text provided by the author or platform.

hashtagsstring[]

Hashtags without #, case kept; [] if none.

mentionsstring[]

Mentioned or tagged usernames without @; [] if none.

is_pinnedbooleannullable

Pinned to the author's profile.

is_sponsoredbooleannullable

Labeled as a paid partnership or branded content.

is_nsfwbooleannullable

Marked adult or sensitive by the platform.

metricsobject

Counts at fetch time; null = hidden or not exposed, 0 = zero.

Show 7 child fields

view_countintegernullable

Views or plays.

like_countintegernullable

Likes, hearts, total reactions or upvotes; never negative. Null when hidden by the owner.

comment_countintegernullable

Comments and replies.

share_countintegernullable

Shares or sends (not reposts).

repost_countintegernullable

Reposts, retweets or reshares.

quote_countintegernullable

Quote posts.

save_countintegernullable

Saves, bookmarks or favorites.

platform_specificobject

Fields only this platform has, under its ID (platform_specific.<platform>); each null when unknown.

Show 5 child fields

tiktokobjectnullable

A TikTok post's own fields.

Show 6 child fields

author_sec_uidstringnullable

The author's secUid, TikTok's account key that survives a rename.

country_codestringnullable

ISO 3166-1 alpha-2 country TikTok registers the post to (not the viewer's).

is_adbooleannullable

The post runs as a TikTok ad.

is_ai_generatedbooleannullable

TikTok labels the post AI-generated.

locationobjectnullable

The tagged place; null when none.

Show 5 child fields

idstringnullable

Place ID.

namestringnullable

Place name.

addressstringnullable

Address line.

citystringnullable

City.

categorystringnullable

Top-level place category.

musicobjectnullable

The post's sound.

Show 7 child fields

idstringnullable

Sound ID.

titlestringnullable

Sound title.

author_namestringnullable

Who TikTok credits for the sound.

is_originalbooleannullable

An original sound a creator uploaded (false: a catalogue track).

duration_msintegernullable

Sound length in milliseconds.

cover_urlstring urinullable

Sound cover image URL.

play_urlstring urinullable

Audio file URL, signed and expiring.

youtubeobjectnullable

A YouTube video's own fields.

Show 12 child fields

categorystringnullable

YouTube category (Music, Gaming, …), in English.

keywordsstring[]

The uploader's tags; [] when none.

chaptersobject[]

Chapters in playback order; [] when none.

Show 2 child fields

titlestringnullable

Chapter title.

start_msintegernullable

Start, in ms from the beginning.

description_linksstring[]

Links in the description, in order, deduplicated; [] when none.

is_unlistedbooleannullable

Unlisted: watchable by link, not listed on the channel or in search.

is_age_restrictedbooleannullable

Viewers must sign in to confirm their age; null when the answer does not tell.

is_paywalledbooleannullable

Must be bought or rented (movies, paid content).

is_live_nowbooleannullable

A live stream on air now.

live_started_atstring date-timenullable

When a live stream or premiere went on air; null if never live.

live_ended_atstring date-timenullable

When a live stream or premiere ended; null while live or if never live.

scheduled_start_atstring date-timenullable

When a scheduled stream or premiere is due to start; null otherwise.

author_subscriber_countintegernullable

The channel's subscriber count, rounded by YouTube (in approximate_fields); null when hidden.

rumbleobjectnullable

A Rumble video's own fields.

Show 15 child fields

embed_idstringnullable

The video's embed player ID (rumble.com/embed/<embed_id>/): its own namespace, not id.

embed_urlstring urinullable

The embeddable player URL.

numeric_idstringnullable

Rumble's numeric video ID, which its own services use.

dislike_countintegernullable

Thumbs-down votes. Exact in Rumble's JSON (shorts, grid lists); a video's page and the older HTML cards cut it to three significant digits from 1,000 (in approximate_fields).

categorystringnullable

Rumble's primary category (News, Podcasts, …).

secondary_categorystringnullable

Rumble's secondary category; null when none.

keywordsstring[]

The uploader's tags; [] when none.

caption_tracksobject[]

Caption tracks (WebVTT); [] when none.

Show 4 child fields

languagestringnullable

Language code (en, es, …).

labelstringnullable

Rumble's label ("English (auto)").

urlstring urinullable

WebVTT file URL.

is_auto_generatedbooleannullable

Generated by Rumble's speech recognition.

filesobject[]

Every file and stream Rumble's player offers, largest video first; [] when none.

Show 7 child fields

kindstringnullable

video (picture and sound), audio (sound only) or preview (the seek bar's low-resolution video, no sound). New values may be added.

One ofvideoaudiopreview

formatstringnullable

mp4 or webm file, hls playlist (all qualities), tar (one HLS quality packed in one file; url is its playlist) or aac audio. New values may be added.

One ofmp4webmhlstaraac

urlstring urinullable

File or playlist URL.

widthintegernullable

Width in pixels; null for audio and playlists.

heightintegernullable

Height in pixels; null for audio and playlists.

bitrate_kbpsintegernullable

Bitrate in kbit/s.

size_bytesintegernullable

File size in bytes; null when Rumble does not state it.

is_live_nowbooleannullable

A live stream on air now.

live_started_atstring date-timenullable

When a live stream went on air; null if never live.

scheduled_start_atstring date-timenullable

When a scheduled live stream is due to start; null otherwise.

concurrent_viewer_countintegernullable

Viewers watching a live stream now; null when not live.

is_age_restrictedbooleannullable

Viewers must confirm their age to watch; null when the source does not show it.

author_follower_countintegernullable

The channel's or user's follower count. Exact in Rumble's JSON (shorts, lists); a video's page cuts it to three significant digits (in approximate_fields).

instagramobjectnullable

An Instagram post's own fields (core/post_instagram.go).

Show 1 child field

is_ai_generatedbooleannullable

Instagram shows its AI label (made or edited with AI); false when it shows none.

facebookobjectnullable

A Facebook post's own fields.

Show 5 child fields

feedback_idstringnullable

Facebook's feedback ID of the post: the thread its comments and reactions hang on.

video_idstringnullable

The video's ID (facebook.com/reel/<video_id>) on a video or reel post; null on other posts.

reactionsobject[]

Reactions by type, most first, as Facebook lists them under the post; [] when none.

Show 2 child fields

typestring

Reaction type. New values may be added.

One oflikelovecarehahawowsadangry

countintegernullable

How many people reacted with it.

shared_postobjectnullable

The post this one reshares; null when it is not a reshare.

Show 3 child fields

idstringnullable

Its post ID.

urlstring urinullable

Its URL.

authorobject

Its author.

Show 6 child fields

idstringnullable

Platform-native account ID; null when only the handle is known.

usernamestringnullable

Handle without the @; null when the account has none.

display_namestringnullable

Display name shown on the profile.

urlstring urinullable

Canonical profile URL.

avatar_urlstring urinullable

Profile picture URL. Platform CDN URLs can expire within hours.

is_verifiedbooleannullable

Platform verification badge; null where the platform has no badge.

linkobjectnullable

The link card a post shares (an article, a site); null when none.

Show 3 child fields

urlstring urinullable

The linked page, as the author shared it (Facebook's l.facebook.com redirect removed).

titlestringnullable

The card's headline.

image_urlstring urinullable

The card's image.

approximate_fieldsstring[]

JSON paths of values rounded by the platform or parsed from display text. A list path (external_links) means the list may be incomplete. [] when all exact.

unknown_fieldsstring[]

JSON paths of lists whose [] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. [] when every list is known.

Item errors

Besides the request-level errors every endpoint can return, post endpoints return:

Code	HTTP	Retry	Meaning	What to do
`not_found`	404	No	The item does not exist or was deleted.	Check the URL or ID; do not retry.
`private_or_unavailable`	403	No	The item exists but is private, age- or region-gated, or requires a login to view. It shares 403 with forbidden (which is about the key): branch on the code.	Only public items can be fetched; do not retry.

not_found, private_or_unavailable (see error codes).