Reference
The unified schema
Five objects cover every platform. A Post from TikTok and a Post from YouTube have the same field names and the same types, so the code that reads one reads the other unchanged.
Two rules that shape everything
Null is not zero. A field is null when the platform does not publish it and zero when the platform publishes a zero. Averaging across a set where those were conflated gives a wrong answer that looks plausible, which is the worst kind.
Nothing is discarded. Normalising is additive. Pass include_raw=true and the original upstream payload comes back beside the normalised one, so a field we have not modelled yet is still reachable.
The envelope
Every successful response has the same outer shape. data is the object, meta is the accounting, and pagination appears only where a list can continue.
{
"success": true,
"data": { /* the unified object */ },
"pagination": { "cursor": null, "hasMore": false, "count": 1 },
"meta": {
"platform": "youtube",
"endpoint": "youtube.channel",
"creditsCharged": 1,
"cached": false,
"cacheAgeSeconds": null,
"durationMs": 412,
"requestId": "req_01JB8Z..."
},
"raw": { /* only when include_raw=true */ }
}Creator
21 fieldsA channel, profile, or page. Follower counts mean subscribers on YouTube and followers everywhere else — the nearest equivalent, always in the same field.
| Field | Type | Notes |
|---|---|---|
| platform | enum | youtube · instagram · facebook · twitter · tiktok · linkedin |
| id | string | The platform-native id — channel id, user id, numeric id. |
| handle | string | null | Without the @. Null where the platform has no handle. |
| displayName | string | null | — |
| bio | string | null | — |
| avatarUrl | string | null | Highest resolution the platform exposes. |
| bannerUrl | string | null | — |
| url | string | null | Canonical public URL. |
| verified | boolean | null | Null when the platform does not say either way. |
| followerCount | number | null | Subscribers, followers, or the platform equivalent. |
| followingCount | number | null | — |
| likeCount | number | null | Total likes where the platform exposes one. Null means not exposed. |
| postCount | number | null | Videos, posts, or reels — whatever the platform counts. |
| viewCount | number | null | Lifetime views where exposed (YouTube, TikTok). |
| isPrivate | boolean | null | — |
| isBusiness | boolean | null | — |
| category | string | null | — |
| location | string | null | Self-declared, not verified. |
| externalLinks | string[] | Empty array, never null. |
| createdAt | string | null | Some platforms publish only a coarse join date. |
| fetchedAt | string | ISO 8601. When we read it, not when it changed. |
Post
21 fieldsA video, Short, reel, image, carousel, or text post. Engagement fields are null when the platform does not expose them, which is not the same as zero.
| Field | Type | Notes |
|---|---|---|
| platform | enum | youtube · instagram · facebook · twitter · tiktok · linkedin |
| id | string | The platform-native id — channel id, user id, numeric id. |
| type | enum | video · short · image · carousel · text · live · story · reel · unknown |
| url | string | null | — |
| title | string | null | Null on platforms without titles. |
| text | string | null | Caption or description. |
| authorId | string | null | — |
| authorHandle | string | null | — |
| authorName | string | null | — |
| thumbnailUrl | string | null | — |
| mediaUrls | string[] | — |
| durationSeconds | number | null | Null for anything that is not timed media. |
| viewCount | number | null | Null means not exposed. Zero means zero. |
| likeCount | number | null | Null when the creator has hidden it. |
| commentCount | number | null | — |
| shareCount | number | null | Null on platforms with no share metric. |
| hashtags | string[] | Parsed from the text, without the #. |
| mentions | string[] | Parsed from the text, without the @. |
| isSponsored | boolean | null | Only where the platform discloses it. |
| publishedAt | string | null | ISO 8601 where exact, otherwise the platform’s own relative text. |
| fetchedAt | string | ISO 8601. |
Transcript
9 fieldsCaptions as one text block plus timed cues. The text block is what most pipelines want; the cues are there when you need to seek.
| Field | Type | Notes |
|---|---|---|
| platform | enum | — |
| postId | string | The video this transcript belongs to. |
| url | string | null | — |
| language | string | null | BCP-47 code of the track that was returned. |
| isAutoGenerated | boolean | null | True for machine captions, which are measurably less accurate. |
| text | string | The whole transcript, cues joined. |
| cues | TranscriptCue[] | { start, end, text } — end is null when the platform omits a duration. |
| durationSeconds | number | null | — |
| fetchedAt | string | — |
Comment
14 fieldsA comment or a reply. Replies carry a parentId; top-level comments do not.
| Field | Type | Notes |
|---|---|---|
| platform | enum | youtube · instagram · facebook · twitter · tiktok · linkedin |
| id | string | The platform-native id — channel id, user id, numeric id. |
| postId | string | null | — |
| parentId | string | null | Null for a top-level comment. |
| text | string | — |
| authorId | string | null | — |
| authorHandle | string | null | — |
| authorName | string | null | — |
| authorAvatarUrl | string | null | — |
| likeCount | number | null | — |
| replyCount | number | null | — |
| isPinned | boolean | null | — |
| isAuthorReply | boolean | null | True when the post’s author wrote it. |
| publishedAt | string | null | — |
Ad
24 fieldsA creative from a public ad library. These are published by regulatory mandate, which makes them the lowest-risk and most reliably available data in the category.
| Field | Type | Notes |
|---|---|---|
| platform | enum | youtube · instagram · facebook · twitter · tiktok · linkedin |
| id | string | The platform-native id — channel id, user id, numeric id. |
| advertiserId | string | null | — |
| advertiserName | string | null | — |
| url | string | null | — |
| headline | string | null | — |
| body | string | null | — |
| ctaText | string | null | — |
| linkUrl | string | null | — |
| creativeType | string | null | — |
| imageUrls | string[] | — |
| videoUrls | string[] | — |
| platforms | string[] | Surfaces the creative runs on. |
| countries | string[] | — |
| languages | string[] | — |
| startedAt | string | null | — |
| endedAt | string | null | Null while the ad is still running. |
| isActive | boolean | null | — |
| impressionsLower | number | null | Libraries publish ranges, not exact figures. |
| impressionsUpper | number | null | — |
| spendLower | number | null | — |
| spendUpper | number | null | — |
| currency | string | null | — |
| fetchedAt | string | — |