# Post

Schemas

A public post (video, reel, short, photo, carousel, tweet or text) with its author, media and engagement metrics.

## Endpoints

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

- [GETFacebook Post API`/v1/facebook/post`](https://staging-fly.socialtap.dev/docs/reference/facebook/post/index.md)
- [GETInstagram Post API`/v1/instagram/post`](https://staging-fly.socialtap.dev/docs/reference/instagram/post/index.md)
- [GETInstagram Posts API`/v1/instagram/posts`](https://staging-fly.socialtap.dev/docs/reference/instagram/posts/index.md)
- [GETRumble Video API`/v1/rumble/post`](https://staging-fly.socialtap.dev/docs/reference/rumble/post/index.md)
- [GETRumble Channel Videos API`/v1/rumble/posts`](https://staging-fly.socialtap.dev/docs/reference/rumble/posts/index.md)
- [GETRumble Search API`/v1/rumble/search_posts`](https://staging-fly.socialtap.dev/docs/reference/rumble/search_posts/index.md)
- [GETTikTok Post API`/v1/tiktok/post`](https://staging-fly.socialtap.dev/docs/reference/tiktok/post/index.md)
- [GETTikTok Posts API`/v1/tiktok/posts`](https://staging-fly.socialtap.dev/docs/reference/tiktok/posts/index.md)
- [GETYouTube Video API`/v1/youtube/post`](https://staging-fly.socialtap.dev/docs/reference/youtube/post/index.md)
- [GETYouTube Channel Videos API`/v1/youtube/posts`](https://staging-fly.socialtap.dev/docs/reference/youtube/posts/index.md)

## Schema

Single-item endpoints return this object as `data`; list endpoints return an array of them as `data` with a [`page`](https://staging-fly.socialtap.dev/docs/pagination/index.md) object. The standard [`meta`](https://staging-fly.socialtap.dev/docs/reference/index.md#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.<br>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.<br>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.<br>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.<br>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.<br>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. |

## Item errors

Besides the [request-level errors](https://staging-fly.socialtap.dev/docs/errors/index.md) 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. |

---

[HTML version](https://staging-fly.socialtap.dev/resources/post/) · [Docs index for AI agents](https://staging-fly.socialtap.dev/llms.txt) · [All docs in one file](https://staging-fly.socialtap.dev/llms-full.txt)