Schema preview Draft
Post schema (draft)
A public post (video, reel, short, photo, carousel, tweet or text) with its author, media and engagement metrics.
Draft: not yet available. No endpoint returns posts yet. This schema may change before the first endpoint ships; don't build against it.
Draft schema
When post endpoints ship, they will return objects shaped like this as data, next to the standard meta, the same on every platform.
| 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. |
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. Often signed and expiring within hours. |
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. |
approximate_fields | string[] | JSON paths of values rounded by the platform or parsed from display text; [] when all exact. |
Item errors
Planned item-level errors, besides the request-level errors:
| 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. | Only public items can be fetched; do not retry. |