Analytics Model - Overlap Docs

Reference for the objects returned by GET /posts and GET /post-analytics. Fields are included when available — a response may omit values that have not been generated yet (for example, engagementScore before the first analytics refresh).

Post object

Field	Type	Description
`id`	string	The post id. Use as `postId` for `GET /post-analytics`.
`platform`	string	Platform the post was published to (`youtube`, `tiktok`, `instagram`, `twitter`, `linkedin`, `facebook`, `threads`, `snapchat`, `bluesky`).
`text`	string	The caption/description that was published.
`postUrl`	string \| null	Public URL of the live post on the platform.
`nativeId`	string \| null	The platform’s own id for the post (e.g. the YouTube video id).
`clipId`	string \| null	The Overlap clip the post was created from. Use with `GET /clip`.
`status`	string	Publish status (`success`, `error`, …).
`mediaUrl`	string \| null	The rendered video/image that was published.
`thumbnailUrl`	string \| null	Thumbnail used for the post.
`createdAt`	string (ISO-8601)	When the post was published.
`analytics`	object	Current rolled-up counters — see below. In `GET /posts` responses this object sits on each post; in `GET /post-analytics` it is returned as the top-level `analytics` object instead.
`engagementScore`	number	See Engagement score.
`growthRate`	number	Percentage growth of the engagement score between the two most recent refreshes.
`lastAnalyticsUpdate`	string (ISO-8601)	When the rollup was last refreshed from the platform.

Analytics rollup object

Field	Type	Description
`views`	number	Current view count. Impressions are used on platforms without a native view metric. Always `0` on Bluesky (no per-post views).
`likes`	number	Current likes/favorites.
`comments`	number	Current comments/replies.
`shares`	number	Current shares/reposts/retweets.
`engagementScore`	number	See Engagement score.
`growthRate`	number	Engagement score growth (%) between the last two refreshes.
`lastAnalyticsUpdate`	string (ISO-8601)	Last refresh time.
`platformMetrics`	object	The platform’s own advanced metrics from the most recent refresh, keyed by platform (e.g. `{"youtube": {"analytics": {"averageViewDuration": 21, ...}}}`). Includes whatever the platform reports — watch time, retention, impressions, subscriber deltas. Shapes mirror the platforms’ APIs and may change without notice. Only on `GET /post-analytics`.

Engagement score

A single number Overlap computes to compare posts across platforms:

engagementScore = (likes × 2) + (comments × 3) + (shares × 4) + max(5, views / 100)

Weighted toward high-intent actions (shares > comments > likes), with a views term so view-heavy posts still register. Use it for relative ranking; it has no absolute unit.

List Posts

Browse posts and rolled-up metrics.

Post Analytics

All current analytics for one post.

⌘I